Introduction
by Pritpal Bedi
hbIDE, as the name implies, Harbour's Integrated Development Environment, is an open-source, multi-platform, project hosted inside Harbour's SVN repository. hbIDE is aimed at simplifying the process of project life-cycle comprising, setting-up the project components, editing the sources, building them to final binaries
hbIDE
2010 Pritpal Bedi
All rights reserved. No parts of this work may be reproduced in any form or by any means - graphic, electronic, or mechanical, including photocopying, recording, taping, or information storage and retrieval systems - without the written permission of the publisher. Products that are referred to in this document may be either trademarks and/or registered trademarks of the respective owners. The publisher and the author make no claim to these trademarks. While every precaution has been taken in the preparation of this document, the publisher and the author assume no responsibility for errors or omissions, or for damages resulting from the use of information contained in this document or from the use of programs and source code that may accompany it. In no event shall the publisher and the author be liable for any loss of profit or any other commercial damage caused or alleged to have been caused directly or indirectly by this document. Printed: May 2010 in (whereever you are located)
Publisher http://www.harbour-project.org Managing Editor Pritpal Bedi Technical Editors Pritpal Bedi Cover Designer Pritpal Bedi Team Coordinator Vik tor Szak ats Production Pritpal Bedi
Special thanks to: Marcos Gambeta - who provided the first constructs to build Harbour wrappers. Vik tor Szak ats - who outlined the project goals and contributed the whole of mak e system plus set right many weired parts. Przemysaw Czerpak - who extended his valuable insight as to the course of structure to base library. Vailton Renato - for implementing build system and providing tons of images. Bisz Istvan - who introduced the extended constructs for garbage collection. Francesco Parillo - who became instrument to find and set right the long-hogging bug in cooeration with Bisz Istvan. Massimo Belgrano - for continually pushing for the project and ask ing new features. Antonio Maniero - for setting wight some artifacts from usability point of view. And all users - who tested, debugged and provided valuable info, tips, comments, to set right which went the wrong direction.
Contents
Table of Contents
Foreword 9
12 14 20
24
1 First Timer ................................................................................................................................... 24 2 Only Editor ................................................................................................................................... 26 3 With Left Panel Docks ................................................................................................................................... 30 4 With Right Panel Docks ................................................................................................................................... 32 5 With Bottom Docks ................................................................................................................................... 37 6 And Bare-boned ................................................................................................................................... 38
40
1 Title Bar ................................................................................................................................... 40 2 Menu................................................................................................................................... 41 Bar 3 Toolbar - Top ................................................................................................................................... 44 4 Toolbar - Left ................................................................................................................................... 50 5 Toolbar - Right ................................................................................................................................... 51 6 Status Bar ................................................................................................................................... 52 7 Projects Tree ................................................................................................................................... 53 8 Editor Tabs Tree ................................................................................................................................... 53 9 Skeletons Tree ................................................................................................................................... 54 10 Editing Area ................................................................................................................................... 54 11 hbIDE Help ................................................................................................................................... 55 12 Documentation Viewer ................................................................................................................................... 56 13 Documentation Writer ................................................................................................................................... 57 14 Functions List ................................................................................................................................... 58 15 Projects Functions List ................................................................................................................................... 59 16 Project Properties ................................................................................................................................... 60 17 Compiler Environments ................................................................................................................................... 61 18 Code ................................................................................................................................... 62 Skeletons
2010 Pritpal Bedi
hbIDE 19 Theme Manager ................................................................................................................................... 63 20 Find in Files ................................................................................................................................... 64 21 Output Console ................................................................................................................................... 65
68 70 72
Part IX Projects
76
Part X Keyboard Mappings Part XI Code Snippets Part XII Tools and Utilities Part XIII Plugins Part XIV Documentation Writer Part XV Documentation Viewer
110 112
2010 Pritpal Bedi
Contents
Part XVIII Thanks and Credits Part XIX Downloads Part XX The Other Links Part XXI hbQT Part XXII hbXBP Part XXIII hbQT - GC - Qt Object Destruction Part XXIV Meet the Author
1 Academics ................................................................................................................................... 136 2 Software Space ................................................................................................................................... 136 3 Contributions ................................................................................................................................... 136 4 Achievements ................................................................................................................................... 136 5 You ................................................................................................................................... 136 may skip...
Index
137
Foreword
Foreword
Dedicated to my wife and daughters who spared me of some duties which led me to allocate more time to this project.
Part
12
hbIDE
Introduction
hbIDE, as the name implies, Harbour's Integrated Development Environment, is an open-source, multiplatform, project hosted inside Harbour's SVN repository. hbIDE is aimed at simplifying the process of project life-cycle comprising, setting-up the project components, editing the sources, building them to final binaries. Currently, only Harbour as a compiler is supported, and hopefully soon, its domain will be extended to xHarbour, Xbase++, Clipper, Clip, Flagship. The central essense of hbIDE is to provide a single-window interface to carry on all related actions for an application project to materialize, without needing any other tool in the process. This concept is extended to make use of n number of C compilers from within the same project definition. For Harbour projects, hbIDE will take use of the its powerful make system, hbMK2. For other compilers, mechanism will be provided to define compiler, linker commands and source definitions. This will, usually, be a one time process, and for rest of the life of the project hbIDE will take over. The topics enumerated at the left are just an indication what will go inside them. I will be updating them as time will permit, though my primary attention is the development of hbIDE. To be just familiar with how the interface may look, a random screen shot of hbIDE, hosting my own production projects is presented below.
Part
II
14
hbIDE
The Origin
Date: 2009-11-17
EMERGENCE OF THIS IDEA ===================== Massimo: initiated idea to have "xMate" or "xMate like" edit/compile/link/run cycle IDE but available for all platforms Harbour support. Viktor: presented the minimum requirements an IDE must contain 0) Availability on OS X, Linux and Windows x86 and x64. 1) Very good editor with block editing capability, syntax highlighting, possibly "intellisense". Project-wide search and replace. Support for all CPs Harbour supports. ( syntax highlighting for: prg, c and cpp ) 2) Integration with VCS. 3) Integrated build tool. 4) Integrated project management. Istvan: extended 3) above as 3.1) Integrated debugger. Francesco: suggested to integrate "Eclipse" which he thought, and others supported, is a great tool, but also expressed that he has no knowledge, so far, how it can be integrated with Harbour. MY VIEWPOINT =========== Since the day Andy started development on xMate, I remained in touch with this project and we had numerous talks about its features. Since then xMate is an integral part of my development cycles. I am rather a dire fan of xMate. As this is a Windows only solution, it will probably be hard to port it to any other platform, unless a great amount of time is not invested into it. As of now I do not have requirements to convert my applications on all platforms and as such xMate completely fulfils my needs. Having said that, still, I am keen on developing an IDE, to a level resembling to xMate ( because of my intimacy as well a big user base ) in functionality but extending it in other ways. ROADMAP TO HBIDE: ================ 0. Development style : PRG 1. Primary coding style : HBXBP 2. Extended calls ( if could not be included in HBXBP ) : HBQT 3. Base protocol for COMPILE/LINK cycle : HBMK2 4. 1st version : xMate like functionality 5. 2nd version : Integration of Qt CREATOR and .ui components 6. ... BENEFITS ( apart from a multi-platform usage ): ======== 1. Xbase++ class framework will be extended to include some very fine Qt extensions.
2010 Pritpal Bedi
The Origin
15
2. HBQT will be extented to include missing components which might be necessary. 3. The resulting application will show up the strength of so many Harbour features. 4. The resulting application will offer a application framework for GUI development to the beginners, i.e., it itself will be a demo application. LOCATION ======== harbour/contrib/hbide NAME ==== HBIDE - Harbour's Integrated Development Environment CHANCES OF SUCCESS =================== Because project is purely based on PRG code, it is highly possible that a lot of you may join this effort, not only for coding but also for debugging, suggestions and whatever... So I see in optimism for its succeess. DETERMINATION ============= I am geared up for its development no matter what will be the consequences, failure or success. First commit will be around this weekend though I am in a position to show you up something. NEXT REQUISIT ============ Your support in terms of vocalness.
2.1
And as of now
hbIDE is 4 months and 10 days old ( as of today: 27Mar2010 ) and hereunder is a brief summary: what it is today, what is proposed, what is on todo list, its strengths, and pitfalls What it is today Implements: multiple projects edit,compile,link cycles with multiple compilers from within single instance. Implements: tracking the compile/link errors and opening the source containing thus error in the editor with offending line under cursor. Implements: multiple editing sessions within a single instance with easy navigation and cut/ copy/paste portability amongst them. Implements: high-performance edit instances with a bunch of features, such as, intelligent autoindentation; in-build keyword capitalization (.prg); ability to switch on/off line-number display; selected block operations: left-right indentation, single-line comments, multi-line comments, double to single quotes, single to double quotes; case conversions: lower to upper, upper to lower, invert cases; line operations: duplicating a line, deletion of line, moving lined in either direction - up/down; and many more.
16
hbIDE
Implements: splitting one edit instance into multiple horizontal and/or vertical windows to edit different parts of the same source simultaneously. Implements: auto-disaster-recovery for every editing instance per minute interval ensuring the maximum amount of loss confined to a minute's work only. Implements: code-skeleton definition and rendering to next levels with user-defined macros and variables in addition to hbIDE defined macros. Implements: tagging of functions prototypes for next levels of function lookups and other "intellisense" features for multiple projects simultaneously. Implements: a reasonable level of "intellisense" providing code-completion lists, on-the-spot function prototype tips, full-blown function overlook, and more. Implements: a powerful "Find-in-files" feature accepting currently-opened edits, contained projects, folders on the disk including sub-folders, options for plain-text or regular expression search, and finally opening the source with currently clicked search-text highlighted in the editor. Implements: a unique "Document Viewer" which pulls the NANFORUM documentation format compliant .txt files from a "root folder" and tree and presents the contents in a navigable browser with options to - "Print", "Save as .pdf", and more. Implements: a unique way to write documentation for functions contained in the editing sessions with options to insert the same into the source at appropriate place or save as a NANFORUM documentation format compliant .txt file on disk which, in-turn, is fully compliant to be viewed in "Document Viewer" if opted as such. Implements: out-of-the-box syntax highlighting for .prg, .c, .cpp, .ch, .h, sources with a provision to set the highlighting themes in the hands of the user as per needs and offering a bunch of predefined themes plus interface to inject your own. Implements: intelligent "book-marks" with visual elements to define, locate and destroy - with least efforts - almost hassle free. Implements: to be used as simple text-editor, a project maintainer and/or builder, or both. Implements: "Tools & Utilities" features which extends hbIDE to take use of any other program, including the DOS prompt, to be executed with parameters from within hbIDE and in a detached manner. Probably it will be wise to extend it to accept parameters comprised of properties of hbIDE components, such as, source file name on disk opened in current editor instance. Implements: saving the current state of hbIDE when exited normally and restores the exact same environment at next run, including the editors state per cursor position, the size and position of the main frame, and lot more. Implements: an interface to define short-cut macros just like xMate plus including some extended functionality. Implements: three types of selection modes: 1. Stream Selection 2. Column Selection 3. Line Selection. All type of blocks are persistent across files. Stream selection mode is a standard text selection protocol implemented by every text editor in the world. Column selection has some peculiar application and Line selection mode offer yet another functionality. All types offer standard cut/copy/paste behavior. Paste operation honors the selection mode, f.e., a block selected under column mode will be pasted as column block. Line blocks overwrite the exiting lines if pasted. Implemented: a simple yet powerful interface to hook third-party plugins designating it truely extensible. What is proposed Visual debugger - someone has to jump in as I know a little about debuggers and their behavior Form editor - which is out of question until we have a complete GUI framework in place. Object browser - what is this ? Version control (SVN) integration - should be easy; need to explore the command-line commands.
2010 Pritpal Bedi
The Origin
17
What is on todo list Wizard based project creation for different compilers - xHarbour, Clipper, Xbase++, Flagship, Clip; for multiple C compilers. Strengths An out-of-the-box experience for Xbase dialect programmers without the hassles of writing tough scripts to achieve high levels of productivity. An all-in-one, composite-components oriented, highly desktop real-estate conscious interface leveraging the levels of productivity to highest extent. With a programmer-oriented approach shedding any inclination of commercial orientation. With highest possibilities to be extended by anyone who does not have any interaction with C language. Pitfalls High memory-intensive back-bone.
Part
III
20
hbIDE
Symantics
This section describes various facts about hbIDE as a whole. The Build How to Initiate
3.1
The Build
hbIDE is a complete PRG level OO ( class code ) implementation and is based on mixed calls to hbXBP and hbQT libraries. It is difficult to distinguish on which primary subsystem it is based on, but, however, demoonstrate the power of using both ways of code frameworks in a single application. This approach has been adopted from the fact that Xbase++ class framework is much limited as compared to the power of Qt classes that not all can be encapsulated in hbXBP unless it is extended to include classes matching that of Qt. It is already planned to enhance hbXBP framework beyond what Alaska offers in Xbase++, and once in place, hbIDE will be overhauled to be based on hbXBP alone. The above description is an abstraction of the whole and may_be/may_not_be grasped by the new comers, so I briefly describe below what these two libraries are all about. hbQT Is a wrappers library for binding Nokis's Qt ( http://qt.nokia.com/ ), a cross-platform GUI framework library. It follows Qt's class hirarchy "as is" and encapsulate its objects in exactly the same way Qt does. We call it - Harbour's Bindings for Qt and is named as hbQT - hb=Harbour Qt=Qt. It is comprised of two components, 1. .cpp compliant functions 2. .prg level Qt compliant class framework, the methods of which, call functions of ( 1 .cpp ). Click here for some detailed knowledge how these two components are working. hbXBP Is a class framework 100% based on Alaska's Xbase++ ( www.alaska-software.com ) and call hbQT's class-methods to render GUI components. It also implements Harbour extensions to enhance Xbase++ compatible classes to new dimensions. The goal is to compile Xbase++ code in Harbour ( and with multi-platform support ) without any changes whatsoever. To some extent hbXBP has been successful in doing so. I am sure, it will absorb Xbase++ code completely in coming future. It is just a matter of time which is always limited. Click here for a detailed view of hbXBP.
3.2
Technical Sheet
This section describes technical details of hbIDE. How to Invoke hbIDE can be invoked with either of the combination, .ini .hbp .prg .c .cpp. Following algorithm is followed: .ini has the precedance over .hbp. if both are passed then .hbp will be added to the project tree, after loading components from .
Symantics
21
ini. if only .hbp is passed, then no attempt is made to save the settings. if only sources are passed then all will be opened "Main" panel, which will also be the startup panel, no project tree will be displayed. Examples C:\harbour\contrib\hbide>hbide.exe hbide.hbp C:\harbour\contrib\hbide>hbide.exe idemisc.prg idethemes.prg C:\harbour\contrib\hbide>hbide.exe C:\dev_hbmk\hbide.ini hbide.hbp Storage Concepts hbIDE stores various informations into a series of files with different formats and locations. hbide.ini: is the standard INI format and stores various settings about the current state of hbIDE. hbide.skt: is the file to store "Code Skeletons" or snippets. It is hb_serialize()d format. hbide.scu: is the file to store user defined "Keyboard Macros" or shortcuts. It is hb_serialize()d format.
Part
IV
24
hbIDE
A Visual Tour
This section will contain the screen shots making the viewer familiar with the interface and judging its capabilities on the surface levels. You are, however, encouraged to study deeply the next topic Understanding interface. These screens are included here under: First Timer Only Editor With Left Panel Docks With Right Panel Docks With Bottom Docks And Bare-boned
4.1
First Timer
First tim e hbIDE is invoked after installation:
A Visual Tour
25
26
hbIDE
4.2
Only Editor
After clicking "Open" top-toolbar icon and selecting a .prg from file-open dialog and navigating few pages dow n:
A Visual Tour
27
After positioning the cursor at line 342 and clicking "Toggle Mark" icon in the top-toolbar and navigating dow n to line 348:
After "Splitting" the editor horizontally via "Split..." option of context m enu:
28
hbIDE
After sw itching off the line-num bers display by clicking "Toggle Line Num bers" icon on left-toolbar:
After sw itching off the split w indow from context m enu, also keeping line num bers sw itched off:
A Visual Tour
29
After sw itching-on the line num bers and and applying a new them e "Evening Glam our" to current editor via context m enu:
30
hbIDE
4.3
A Visual Tour
31
32
hbIDE
4.4
After providing the "Harbour Installation Root:" and searching "ascan" under "Index" tab:
A Visual Tour
33
34
hbIDE
A Visual Tour
35
After clicking "Com piler Environm ents" icon on the right-toolbar and retaining tooltip w hile hovering over blank edit box:
After clicking "Code Skeletons" icon on right-toolbar, (luckily I had few skeletons defined already w hich are visible inside, though it w ill be blank first tim e):
36
hbIDE
After clicking "Them e Manager" on right-toolbar, the height is autom atically expanded a little because of m any controls in it:
A Visual Tour
37
4.5
38
hbIDE
4.6
And Bare-boned
After hiding all left and right toolbars and line num bers display - as sim ple as could be:
Part
40
hbIDE
Understanding Interface
This section will explain the various parts of the user-interface and their relation to each other. The understanding of it will help using the features to maximum efficiency. For this purpose, a loaded instance of hbIDE, hosting some of my projects, is captured to demonstrate interface components.
The presented screen is obtained after activating "Projects", "Editors", "Skeletons" trees at the left-hand and "Functions List" at the right-hand panels:
Further analysis of the different parts of the interface are discussed at various topics beneath it. Title Bar Menu Bar Top Toolbar Left Toolbar Right Toolbar Statusbar
5.1
Title Bar
The various components of hbIDE's title-bar can be best grasped as under
Understanding Interface
41
5.2
Menu Bar
hbIDE's main menu bar contains following entries:
Menu Bar
<Files>
42
hbIDE
<Edit>
<Projects>
Understanding Interface
43
<Build>
<Setup>
<View >
44
hbIDE
<Help>
5.3
Toolbar - Top
This section describes the different elements of hbIDE's top-toolbar.
Understanding Interface
45
Exits hbIDE
Ctrl+Sh+W
Unlike "X" button, this action does not ask for confirmation whether user really wants to exit. Hosts two tabs: 1. Welc ome, displa ying statist ics for hoste d projec ts with drilldown featur e. 2. FAQ's , providi ng answ ers to some FAQ's
Panel: Stats
New editor instance MenuBar->Files->Newwith title "Untitled" on >Source the active panel.
Ctrl+N
At this invocation no syntax highlighting theme is assigned to the source. It is the responsibilit y of the user to save it with valid extension and then
46
hbIDE
reopen the same to have theme activated. File Open Dialog to MenuBar->Files->Open select a source to be edited. Ctrl+O The selected file is tested against hbIDE's supported formats and an alert is issued if it does not matches and operation is abandoned. The save operation is silent, no alert is issued. If the instance is in "Modified" state than an alert is issued to confirm if it be saved first before closing. Print Preview dialog offers a variety of options from controlled printing to export to various formats, such as PDF.
MenuBar->Files->Save
Ctrl+S
MenuBar->Files->Close
Ctrl+W Esc
Ctrl+P
Compiles active Context-menu->Compile editing instance if it is a .prg source. Compiles active editing instance to . ppo format if it is .prg source. MenuBar->Build-Compile to PPO Context-menu->Compile to PPO If compile succeeds, opens .ppo into a new editing instance.
Understanding Interface
47
MenuBar->Build->Build Project
If no project is set as "current" ( c an be confirmed from statusbar panel ), a list of hosted projects is presented to select one. If some source from this project is opened in any of the editing instances, and is in a "Modified" state, then thus source is saved before "Build" process starts. This explanation holds good for next three options.
Builds current project MenuBar->Build->Build and and Launches it if Launch successful. Re-Builds the current project. MenuBar->Build->Re-build Project
Re-Builds the current MenuBar->Build->Re-build project and Launches and Launch it if successful Undo one recent edit operation. MenuBar->Edit->Undo Context-menu. Ctrl+Z Undo and next 11 options are editing actions which are always carried on
48
hbIDE
active edit instance or split. Redo one recent MenuBar->Edit->Redo undone edit operation Context-menu. Cuts the selected text MenuBar->Edit->Cut if any. Context-menu. Copies selected text onto clipboard Pastes the clipboard text at current cursor position. MenuBar->Edit->Copy Context-menu. MenuBar->Edit->Paste Context-menu. Ctrl+R This shortcut cannot be over-ridden.
Del Ctrl+C This shortcut cannot be over-ridden. This shortcut cannot be over-ridden. This shortcut cannot be over-ridden. At present only streamselection is available. I am working hard to get columnselection working and will be available some-time in future.
Ctrl+V
Selects the entire MenuBar->Edit->Select All contents of active edit instance. Flags if current selection mode is stream or columns.
Ctrl+A
Invokes Search & Replace Dialog Toggles a bookmark on the current line.
MenuBar->Edit->Find / Replace
Ctrl+F A visual representatio n of the bookmark is placed as a colored rectangle at the left of line-numbers display area and the line is also painted with same color as background. The line
Understanding Interface
49
color is persistent and is brought to notice whenever the segment of source containing it is navigated to viewport of the editing instance. A correspondin g button on a panel in status-bar also appears with same color as that of marker and facilitates to jump to that particular bookmark line whenever clicked. In all, one editing instance can have 6 bookmarks maximum at any given moment. Goto Line Dialog Zooms-In the text with larger fonts. MenuBar->Edit->Goto Line Ctrl+G Note that there is no way of returning back to original font. The only way to achieve so is
50
hbIDE
either close the instance and open again or rerun hbIDE. Zooms-Out the text with smaller fonts. Tools & Utilities Dlg. DnArrow: drop-down menu to invoke a Tool. Creates or brings an existing panel to front. Though you are free to create n number of panels, but still take care of lefttoolbars being overburdene d.
5.4
Toolbar - Left
Left toolbar in-fact is composed of two toolbars-in-one. The upper part is comprised of "Panel Buttons" corresponding to user created panels to host editing instances, and the lower part is comprised of actions specific to lines and block selections. The "Panels" toolbar is expected to grow downwards corresponding the number of panels.
Toolb Butto ar n
Invokes
Alternate
Shortcut
Public Method
Description
Editor Panel "Main" Current Line Down Current Line Up Delete Current Line Duplicate Current Line
Top-Toolbar "Panels Icons"s Drop-down Menu Main Menu->Edit- Ctrl+Sh >Line->Current +Dn Line Down Main Menu->Edit- Ctrl+Sh >Line->Current +Up Line Up Main Menu->Edit- Ctrl+Del >Line->Delete Current Line Main Menu->Edit- Ctrl+D >Line->Duplicate Current Line
Understanding Interface
51
Toggles Line Numbers Display Converts to Upper Case Converts to Lower Case Inverts Case Single Line Comment Stream Comment Main Menu->Edit- Ctrl+Sh >Block->Single +/ Line Comment Main Menu->Edit- Ctrl+Sh >Block->Stream +Q Comment
Button's depressed state denotes that line numbers display is off. This toggle is valid for all editor instances and the setting is remembered for next run.
Indents One Main Menu->Edit- Ctrl+Ta Column Right >Block->Indent b Right Indents One Column Left Single Quotes to Double Double Quotes to Single Main Menu->Edit- Ctrl+Sh >Block->Indent +Tab Left Main Menu->Edit>Block->Single Quotes to Double Main Menu->Edit>Block->Double Quotes to Single
5.5
Toolbar - Right
Right toolbar is specific to toggling the docking widgets hosted at left, right, or bottom areas of the main window. Below are facts to be noted about them: If a "dock" is in invoked state, the icon will appear "checked". Bottom area dock widget "Output Console" is automatically invoked when a projects is "Build". Left and bottom area docking widgets remain non-detachable, i.e., these cannot be separated from attached area and hanged somewhere else. Right area docking widgets can be detached and hanged anywhere on the screen. Detachable widgets will always remain on top of the main window and cannot be minimized or put behind the main screen. Left area docking widgets retain their positions at the next run and are made visible. Right area docks will retain their position and size if detached but are not made visible at the next run. However these widgets will be opened at the last saved state if invoked.
Invokes
Docking Area
Attributes
Alternate
Other Links
52
hbIDE
Project Tree Editors Tree Skeletons Tree hbIDE Help Document Viewer Document Writer Functions List Project(s) Functions List Project Properties Compiler Environments Code Skeletons Theme Manager Find-inFiles Manager Output Console
NonMain Menu->View->Projects Detachable NonMain Menu->View->Editors Detachable NonMain Menu->ViewDetachable >Skeletons Detachable Main Menu->View->hbIDE Help Detachable Main Menu->View->Harbour Documentation Detachable Main Menu->View>Documentation Writer Detachable Main Menu->View>Functions List Detachable Main Menu->View->Projects Functions Lookup Detachable Main Menu->View->Project Properties Detachable Main Menu->View->Compiler Environments Detachable Main Menu->View->Code Skeletons Detachable Main Menu->View->Theme Manager Detachable Main Menu->View->Find in Files NonMain Menu->View->Output Detachable Console
See Also:
Main Menu->View
5.6
Status Bar
This section describes various panels of status-bar and explains the contents therein.
Understanding Interface
53
5.7
Projects Tree
Projects tree depicts the projects hosted inside for current session. It also provides the interface to Create, Load, Build and various other actions associated with projects and the source files comprising those projects. Projects tree is a left-side docking widget and has an attribute to hide or show, resize, etc. This setting is remembered for subsequent run. It exposes standard navigational behavior, viz., left-click: selects node, right-click: context-menu, double-click: activates next action depending upon the node type.
5.8
54
hbIDE
5.9
Skeletons Tree
Code snippets or skeletons are implemented in a powerful way in hbIDE. One of the major feature of this implementation is the ability to place Harbour functions from RTL to build code lines.
5.10
Editing Area
Editing Area is comprised of "Panels" and "Editing Instances" hosted onto those panels. The concept of "Panels" can be taken as synonymous to "sessions". Each panel can host n number of editing instances. It can be termed as epic-center of hbIDE. All other components are ancillary to the working of hbIDE.
Understanding Interface
55
5.11
hbIDE Help
There is very little to hi-light about this feature. Still do not know will it make up in the final distribution or not. However, for beginners, this may provide some food for thought in their own applications.
56
hbIDE
5.12
Documentation Viewer
Documentation Viewer provides an hbIDE-unique feature to view Harbour and/or own documentation (NANFORUM compliant format) in an interlinked GUI environment.
Understanding Interface
57
5.13
Documentation Writer
Documentation writer is a unque-to-hbIDE interface which provides the necessary constructs to include documentation right along the function body or separately on the disk confirming to NANFORUM documentation standards.
58
hbIDE
5.14
Functions List
Functions List presents all the functions contained in the source open in current active editor instance and provides a convenient way to reach to any one by double-clicking on its node in the list.
Understanding Interface
59
5.15
60
hbIDE
5.16
Project Properties
Project Properties dialog is the epic-center of complete project management.
Understanding Interface
61
5.17
Compiler Environments
Environment settings plays an important role if hbIDE is used to build projects.
62
hbIDE
5.18
Code Skeletons
Code skeletons, if defined properly, is a powerful way to reduce development time.
Understanding Interface
63
5.19
Theme Manager
Theme manager lets you control the look and feel of editor instances plus allows to define rules for syntax-highlighting.
64
hbIDE
5.20
Find in Files
Find-in-files utility in hbIDE is a powerful component and provides a convenient way to search projects, open sources, and/or folders to locate a string.
Understanding Interface
65
5.21
Output Console
Output Console is the placeholder for all compile/link generated output, standard or error.
66
hbIDE
Part
VI
68
hbIDE
Book Marks
Enter topic text here.
Part
VII
70
hbIDE
Panels
hbIDE implements concept of Panels which are the containers to host various interfaces it exposes. Currently, two types of panels are in implementation: 1. Stats: is of fixed type and is always presented in focus whenever hbIDE is run. This panel hosts two tabs - 1. Welcome and 2. FAQ's 2. Editors: is of variable number. Panel named "Main" is always present and cannot be removed. n number of other panels can be created by user.
Part
VIII
72
hbIDE
8
8.1 8.2 8.3
8.3.1
Sources
Enter topic text here.
Loading
Enter topic text here.
Creating
Enter topic text here.
Editing
Enter topic text here.
Intellisense
hbIDE implements the concept of "intellisense" in a unique way. The concepts employed are not said to be "exhaustive" but provide a fair degree of guidance to the developer. The concepts are a mix of traditional way and something unique to hbIDE. In the follwoing pages we will discuss its various usages and benefits. To be a little comfortable below is the ChangeLog entries in the SVN. Click on "ffn" icon on the right-toolbar or select "Projects Functions Lookup" in "View" menu. In the opened dock-widget, click on "Mark Projects" button. On the top of widget, a list of all projects loaded will appear. Click in the little check boxes left to the project titles. You can choose n number of combinations. Click on "Re-Tag" button, if this is the first time you are tagging project(s), or "Load Tags" if you already have tagged before. Keep a watch on right-corner of "Syntax" box, it will show the running commentary. After a while the table above will be populated with function info: Name Type Line Project Source. Type some alphabets in the top-most edit control. It will position the function matching the typed characters in the table. Double-click on some function in the table, it will be opened in the editor. The "intellisense" part, above was basic mechanism to gather contents: Type in the editor a function name which you think must have made up in the exercise carried above. The moment you will type "(" a nicely formatted tooltip, displying the prototype of this function will appear beneth the caret position. The prototype will remain there for 10 seconds ( finding a way how it can be controlled the way I want ). Position editor caret somewhere in some function characters and activate context menu with right click. Select "Goto Function" option.It will open the underlying source with cursor positioned on the function proto. Siultaneously, the function will be made current in the table in "Projects Functions Lookup" widget.
Sources
73
Part
IX
76
hbIDE
Projects
At present hbIDE supports projects specific to Harbour as compiler. However any language dialect can use it for organizing the projects and editing tasks taking use of hbIDE's powerful interface. Hopefully soon, support for following languages will be implemented, strictly in the order given below: 1. 2. 3. 4. 5. xHarbour Xbase++ Clipper Clip Flagship
Projects
77
78
hbIDE
9.1
Loading
To be on quicker side below are the steps to load a project: ( more details will follow in the coming days )
Run hbIDE Right-click the "Projects" node of "Projects" tree. Select "Open Project..." Select exiting project file ( Harbour .hbp, xMate .xhp ) Project will be added in the project tree. [ One-time Settings ] Click on "Compiler Environments" icon on right-toolbar.
2010 Pritpal Bedi
Projects
79
Click on folder icon next to "Path to hbIDE env:" field. Select "hbide.env" file from fileopen dialog and click "Open" button. [ Infact, you are encouraged to copy this hbide.env file at the root of your projects folder and then make changes to confirm to your workings ] Edit contents loaded from this file in the editor to suit paths to different compilers to match your workings. Click "Save and Exit" button at the bottom, Dialog will disappear. [ /One-time Settings ] Right click on project name node in the "Projects Tree" and point to "Select an Environment..." and select one from the popup menu. Thus selected environment should be visible in "Env:" panel of status-bar and remain valid for any next project "build" until changed. Also this setting is retained intact for next run. Build the project.
9.2
Creating
Let's take a visual tour to create a project step-by-step:
80
hbIDE
Projects
81
82
hbIDE
Projects
83
84
hbIDE
9.3 9.4
Building
Enter topic text here.
Compiler Environments
hbIDE implements everything-in-one approach to define C compilers configurations. The file which stores thus settings is hbide.env. The interface implements a slot to hold the path to this file. By default it is searched where hbde.ini is loaded.
A Pictorial Overview
Projects
85
The contents in this file m ay look like this ( this is from m y production environm ent - BTW ):
[ MINGW 4.4.2 ] {hbmk2} -inc {content} set HB_COMPILER=mingw {content} set PATH=C:\mingw\bin;%PATH% {content} set PATH=C:\harbour_dev;C:\harbour_dev\harbour\mingw\bin;% PATH% {content} {content} {content} {content} set set set set HB_INSTALL_PREFIX=C:\harbour_dev\harbour\mingw HB_INC_INSTALL=C:\harbour_dev\harbour\mingw\include HB_LIB_INSTALL=C:\harbour_dev\harbour\mingw\lib HB_BIN_INSTALL=C:\harbour_dev\harbour\mingw\bin
[ BCC55 5.5.1 ] {content} set HB_COMPILER=bcc {content} set PATH=C:\harbour_dev;C:\harbour_dev\bcc\bin;C: \harbour_dev\harbour\bcc\bin; {content} set HB_INSTALL_PREFIX=C:\harbour_dev\harbour\bcc {content} set HB_TR_SYSOUT=yes
86
hbIDE
[ MSVC 8.0 ] {content} set HB_COMPILER=msvc {content} call "%ProgramFiles%\Microsoft Visual Studio 9.0 \VC\vcvarsall.bat" x86 {content} set PATH=%ProgramFiles%\Microsoft Visual Studio 9.0\VC\bin;% PATH% {content} set PATH=C:\harbour_dev;C:\harbour_dev\harbour\msvc\bin;%PATH % {content} set HB_INSTALL_PREFIX=C:\harbour_dev\harbour\msvc {content} set HB_TR_SYSOUT=yes
The content in "[ ]" square brackets is the environment name and also the delimiter for next environment. This name will be available to be selected in the context-menu on project name node of "Projects Tree". This is for informative purposes but you are encouraged to keep it as short as possible because it is displayed in the status-bar on selection. {hbmk2} is the placeholder for parameters passed to hbMK2 directly on the command line. hbMK2 accepts two types of parameters; 1.included in the .hbp; 2. passed on the command line. For more details please read INSTALL. So this placeholder is the only way to pass command-line parameters hbMK2 will be expecting. {contents} is the placeholder to accept all those commands which can be placed in a shell specific .bat or .sh file. The information provided with {contents} becomes the body of such shell executable and is executed prior to invoking hbMK2. "#" - hash is the only comments delimiter and must be specified as the first character on a new line followed by comments line. All the environments defined as above are included in the context-menu. Last environment selected is retained for next-run. The hbide.env file created as above is remembered and is loaded next time hhIDE is invoked. This implementation ensures that you can link your projects with multiple compilers from within the same instance of hbIDE. Just change the environment from context-menu and compile. If you have provided the right kind of flags to hbMK2, chances are your projects will be build fine in first attempt. I use it extensively. Take use of it. But the is not mandatory. You can still build your projects if you invoke hbIDE from console which is already configured for a compiler. In the absence of selection from context-menu, default environment prevailing is used.
Part
88
hbIDE
10
Keyboard Mappings
hbIDE provides an interface similar to xMate to define keyboard shortcuts where each shortcut may be a big piece of code comprising Harbour functions and hbIDE's public methods API. Following image may well describe its various components.
Keyboard Mappings
89
Part
XI
92
hbIDE
11
Code Snippets
How to write ========= * Click <Docks> main-menu option and select <Code Skeletons>. * "Code Skeletons" window will open at the right-docking area. * Close other docks if open to make room for its components. * Click <Add New> button, a dialog will appear requesting a "Name". * Enter recognizable name for this skeleton, i.e., "DO CASE 3", where "3" will represent that this case statement contains 3 iterations of CASE statement. It is just an example, follow your way of recognitions. * After you click <ok> the name will appear in "Identity" list-box. * Start writing in "Code Snippet" editor, like: DO CASE CASE x == CASE x == CASE x == ENDCASE * After you are done with it, click <Update>. * Repeat the process for some other skeletons. * Do not forget to click <Update> even after slightest modification. This will ensure that your skeleton is always in order. * If you wish to change the name, click on that "Name" in "Identity" list-box and click <Rename>, follow next process. Click <Update> to save permanently. * <Delete> is not working yet. * Navigate the skeletons by clicking on the prompts; you will find the attached code in the editor below. How to Call ======== * While in the editor tab, position your editing cursor at desired column. * Press Ctrl+K, a context menu will appear near left-upper part of the editing tab containing all skeletons you wrote. * Use arrow-up/down keys to desired skeleton and press <Enter>. * The code skeleton will be inserted in the source aligned to the column you started with. The cursor will be anchored on the same place. * Alternativly you can use mouse, but keyboard navigation is simple in this context. * Note that alignment and indent of inserted code skeleton is perfect to starting column.
1. Creating of skelton is as before with same interface. 2. In addition, the selected text in the current editor can be saved as a skeleton via "Save as Skeleton..."
Code Snippets
93
option in right-click context menu. A "Name" will be asked via a modal input edit dialog. 3. A new "Skeletons" tree-view is implemented at the Left-hand docking area which displays all skeletons by name. 4. Hovering cursor over the name node shows up the body of skeleton as a tooltip, very handy. 5. Double-click on the node in tree-view will insert the skeleton text at the current cursor position. 6. Alternatively, as before, menu can be activated via CTRL+K. 7. Skeletons body now supports meta data as follows: --DO WHILE .T. IF cVar == "<-PROMPT>" xVar := <-DtoC( Date() )> ENDIF <-CUR> EXIT ENDDO --You can see there are 3 occurances of <-*> token. <-PROMPT> will execute an input dialog and the resultant string will be inserted here. <-DtoC( Date() )> will evaluate the expression, which in this case, - "03/18/2010" - will be inserted. This means any valid Harbour expression which returns a string can be designated as meta-expression. <-CUR> will position the cursor at this place. ! Meta concept enhanced further. <-NAME=PROMPT> ; then NAME will be the meta and string returned by PROMPT dialog will be assigned to <-NAME> for next occurances. The assignment is done only with <-PROMPT> meta. This feature is especially useful when skeleton is built defining a class: --- SKELETON --#include "common.ch" /*------------------------------*/ CLASS <-NAME=PROMPT> INHERIT IdeObject
2010 Pritpal Bedi
94
hbIDE
DATA oUI METHOD new( oIde ) METHOD create( oIde ) METHOD destroy() ENDCLASS /*------------------------------*/ METHOD <-NAME>:new( oIde ) ::oIde := oIde RETURN Self /*------------------------------*/ METHOD <-NAME>:create( oIde ) DEFAULT oIde TO ::oIde ::oIde := oIde RETURN Self /*------------------------------*/
--- INSERTION ( after input "MyNewClass" in the dialog ) --#include "common.ch" /*------------------------------*/ CLASS MyNewClass INHERIT IdeObject DATA oUI METHOD new( oIde ) METHOD create( oIde ) METHOD destroy() ENDCLASS /*------------------------------*/ METHOD MyNewClass:new( oIde ) ::oIde := oIde RETURN Self
2010 Pritpal Bedi
Code Snippets
95
/*------------------------------*/ METHOD MyNewClass:create( oIde ) DEFAULT oIde TO ::oIde ::oIde := oIde RETURN Self /*------------------------------*/
Part
XII
98
hbIDE
12
How to Invoke
Clicking the <Tools> button on top-toolbar brings up above dialog. Clicking on drop-down menu of <Tools> button's down-arrow invokes the selected tool.
Fields
Name: can be provided manually or will be pulled from <Command Line> if an application is searched with by clicking on <Browse>. This name is displayed in the drop-down menu of "Tools" button on the top-toolbar. This name can also be supplied to public method :: execTool( cName ). Command Line: placeholder of executable's path which can be provided manually or can be searched by clicking on <Browse> button. This is the application which will be invoked with a click on <Execute> button or clicking on drop-down menu of. If left blank, it will invoke
2010 Pritpal Bedi
99
shell command. This field is subject to normalization of path. Parameters: placeholder for arguments to be supplied to application defined in <Command Line>. If no application is defined then this field will be considered as application(s) with parameters. This field is subject to path normalization and hence character "/" and "\" will be treated as path separators. Normalization is not applied if "http://" is a part of this field. It implied that "/" must not be used for command line arguments. You are encouraged to use hiphen "-" instead of slash "/" for this purpose. Start In: placeholder the path which will be made current before invoking the application. It helps in fine-tuning the behavior if some environment is dependent on fixed locations for any components. Capture Output: placeholder to flag if the tool defined herein is invoked as "attached" to this process and is subject to capture the standard and errors output ? If switched ON, the behavior of this utility will correspond to one which is employed for "building" a project, with same features as to tracking the link/compile errors. This opens up the possibilities to execute edit/compile/link cycle for n number of languages and compiler for which hbIDE does not support yet. See "Xbase++" example below. Open Output Window: placeholder to flag which tells hbIDE to invoke "Output Consoke" docking widget at the bottom of editing area. This has relevance only if "Capture Output" is also checked. This feature is especially useful in cases when we are invoking files which are associated to some other application but we do not want to see the shell command window. Please see examples below to understand its behavior fully.
Examples
1 Name hbIDE : opens an instance of hbIDE as a pure editor with hbide.prg opened in an edit tab. We are supplying source name with the full qualified path and are not caring for from where it is invoked. The other alternative could be: <Parameters> hbide.prg <Start In> C:/harbour/ contrib/hbide/. C:/harbour/contrib/hbide/hbide.exe C:/harbour/contrib/hbide/hbide.prg
Xbase++ : compiles and links an Xbase++ project and traps errors in the output window from where you can reach to the offending line by double clicking, much like if an Harbour project has been built. C:/batches/xp_env/alaska90.bat && xpp -q C:/harbour/tests/speedtst.prg && alink speedtst C:/harbour/tests Yes Yes
100
hbIDE
Public Method
hbIDE provides two ways to call a tool as its public methods API. 1. ::execTool( cName ). <cName> is the name of the tool and must be already defined before calling, otherwise no action will take place. 2. ::execTool( cCommand, cParams, cStartIn, lCapture, lOpenOutputConsole ) if called like this it does not look for any pre-defined definition. If none of the parameters is supplied, a shell command window will be invoked.
Part
XIII
102
hbIDE
13
Plugins
The concept of "Plugins" is quiet old and all the major tools provide some interface to hook thirdparty plugins to extend the domain of such tool. hbIDE also provides such interface. Below is the initial ChangeLog entry text which describes this protocol.
2010-05-09 20:11 UTC-0800 Pritpal Bedi ([hidden email]) * contrib/hbide/hbide.prg * contrib/hbide/ideplugins.prg % Changed: plugins are loaded on first call instead of loading all plugins at startup. Now the overhead is negligible. 2010-05-09 17:21 UTC-0800 Pritpal Bedi ([hidden email]) + contrib/hbide/plugins + contrib/hbide/plugins/savebackup.hrb + contrib/hbide/plugins/savebackup.prg + Source and corresponding .hrb ( -gh ) plugin. In practice .prg is never required for this purpose. The source accompanying here is for demonstration purposes which exposes elements to comprehend. + contrib/hbide/resources/selectionline.png + Image to be activated when "Line" selection mode is on. * contrib/hbqt/hbqt_hbqplaintextedit.cpp * contrib/hbide/hbide.hbp + Added ideplugin.prg * contrib/hbide/idethemes.prg + Added more keywords for syntax-highlighting. * contrib/hbide/hbide.prg * contrib/hbide/idedocks.prg * contrib/hbide/ideedit.prg * contrib/hbide/ideeditor.prg + contrib/hbide/ideplugins.prg + Priliminary commit to handle plugins. * contrib/hbide/ideshortcuts.prg + Implemented: a very simple yet powerful interface to hook plugins.
2010 Pritpal Bedi
Plugins
103
The idea got polished with Francesco Perillo's description of the thought. Creating a hbIDE plugin ======================= A .hrb ( compiled with -gh as the minimum ), i.e., savebackup.prg, having two mandatory functions: 1. hrb_file_name_without_extension_plus_underscrore_plus_INIT() savebackup_INIT( ... ) -> TRUE/FALSE 2. hrb_file_name_without_extension_plus_underscrore_plus_EXEC() savebackup_EXEC( oIde, ... ) -> xValue savebackup_INIT() will be used to establish hand-shake and it must return a logical indicating success or failure. Currently it is called with "1.0" as version no but is scheduled to be enhanced in future. If hand-shake is successful, means, savebackup_INIT( ... ) returns with TRUE, savebackup_EXEC( oIde, ... ) is called as per user request. oIDE is sent as the first argument followed by user supplied arguments. Within this function in .hrb, all action takes place. User can write n number of functions withing the same source but all other functions will always be STATIC ones. The whole hbIDE object is passed with each execution and hence user is having utmost control over what he wants to accomplish. Location of the Plugin ====================== All plugins ( .hrb ) must reside within "plugins" sub-folder from hbIDE.exe location. The location is determined with return value of hb_dirBase() + hb_osPathSeparator() + "plugins" + hb_osPathSeparator(). Loading Plugins =============== At startup hbIDE looks into "plugins" folder for all .hrb files. It then tries to establish hand-shake with them. If successful, a handle is retained in static array. When an execution request is encountered, this static array is searched for and savebackup_EXEC( oIDE, ... ) is called and return value is passed back to the caller macro. Executing Plugins in hbIDE ==========================
104
hbIDE
A public method ::execPlugin( cPlugin, ... ) is implemented under "Keyboard Mappings". ::execPlugin is called with plugin name, which essentially is the .hrb file name. So in demo example, it is "savebackup". Final expression would be like : ::execPlugin( "savebackup", "saveas" ) Here "saveas" is the identifier which is used in this demo to invoke STATIC FUNCTION savebackup_saveAs( oIde ) Author of plugin has to decide how and what he would like to pass what and in how many. So simply build a macro to call a plugin with parameters, that's it. I am hopeful that you, brilliant programmers, with help extending hbIDE to an amazing levels. Send your critics to the list to enrich this thought.
Part
XIV
106
hbIDE
14
Documentation Writer
It is a quick way to generate help. You can keep the documentation in your sources or can create a tree like Harbour's. I know there is a lot more to be done in this tool, but at least group can start using it.
1. 2. 3. 4.
Click on "Documentation Writer" icon on the right-toolbar, Open some source in the editor, Position cursor somewhere inside a function body, Click on "Load from current function" icon on the top-toolbar of "Document Writer" widget, 5. Look at the contents, few fields will be auto filled with various info from current function, 6. Complete the other fields with relevent information, 7.1 Click on "Save the documentation with current function", .2 Look at the function body in the editor, The NANFORUM compliant documentation will be inserted at the top of function's prototype. 8.1 Click on "Save written/updated documentation" icon, and provide the filename to save on disk, .2 Copy such generated .txt in /harbour/doc/en, .3 Open "Harbour Document Viewer" and you should be viweing newly written documentation there. .4 Such generated file is ready to be uploaded to SVN, just send it to the list and group will decide if it needs something extra.
Part
XV
108
hbIDE
15
15.1
Documentation Viewer
Enter topic text here.
Understanding Interface
Enter topic text here.
15.2
Navigate Topics
Enter topic text here.
Part
XVI
110
hbIDE
16
Themes
The concept of Themes in hbIDE is synonymous to syntax-highlighting rules rather than application theme. hbIDE provides an xMate like interface to change, add, apply, save themes. It also provides for applying the themes to individual editing instance level.
Part
XVII
112
hbIDE
17
Public Methods
hbIDE is scheduled to implement some methods which may be called from user-defined macros inside the editing instances through shortcuts or menu options. Soon this protocol will be in the SVN. To keep myself and upto-date of what "should be" and "has been" implemented, here is the list of such methods which I think should make-up the bunch. Please note that these methods are along the lines of xMate and initial list below includes all methods contained in xMate v1.15.
Method Stat Curr us ent Description Links
::AlignOperator()
Aligns the assignment operators within the top and "OperAlign.txt" the bottom of the current selection. Column selection provides for special features. Opens the buffer nomination dialog, and appends the currently selected text to the nominated scratch pad buffer Auto-completes the initiated key. Creates the backup file See the editor configuration for backup file extension options. Starts buffering the operations that follow, into a single undo step. Also see the EndUndo() method. Saves all updated files and builds ( makes ) the application. The optional <lRebuild> flag will cause the complete rebuild of the project. Saves all updated files and builds ( makes ) the application. The application is launched, if the build as successful. The optional <lRebuild> flag will cause the complete rebuild of the project. Clears the Undo buffers. Closes all files and exits the editor window. Closes the current file. Displays the code skeletons selection dialog. Places the editor into function summary mode. Adds, or removes comment indicator "//" from the beginning of the selected lines of text. Compiles the current file. Creates the PPO output from the current file, if applicable. Copies selected text into the Windows clipboard Deletes the selected text, and places it in the Windows clipboard. Deletes line <n>. The default line is the current line. NOTE that the complete macro for deleting a line should read: "complete.txt"
::AppendScratchPad()
::BuildAndRun ([<lRebuild>])
::ClearUndo() ::CloseAll() ::CloseCurrent() ::CodeSkeletonsDlg() ::Collapse() ::Comment (<lComment>) ::CompileCurrent() ::CompileToPPO() ::Copy() ::Cut() ::DelLine( [<n>] )
Public Methods
113
::DelLine(::line), IF(::Line > ::Lines, ::Up(), NIL), . F. ::DelRest() ::DelScratchPad() ::DelText() ::DelWordRest ([<cOperators>]) Deletes the reminder of the line. Opens the buffer nomination dialog, and deletes the nominated scratch pad buffer Deletes the selected text. Deletes characters till the end of the word. Distinguishes [<cOperators>] from the regular alphanumerical characters, as separate words. The default <cOperators> are: '<>,.?/';:\|{}[]=-+() &&*%^#$!@~`" . Attempts to move down <n> lines ( default 1 ). Duplicates the current line, by inserting it directly below the current line. Places the caret at the end of the current line. Submits the editing steps for examination to the undo engine, to create a single undo step. Also see the BeginUndo() method. Clears summary mode, and places the caret at the beginning of the currently highlighted function. Displays the search and replace dialog. The optional parameters are: lUseWordUnderCursor - set to TRUE to paste the word under cursor (default) lAutoMode - set to TRUE to let the dialog set the search mode automatically (default) lListOnly - set to TRUE to turn on the result listing. Finds the matching bracket to the one at the current caret position. Atempts to continue the most recent search. Finds the specified text, uses either the supplied parameters, or the last used method of searching.
::FindMatch() ::FindNext() ::FindText( <cFind>, [<lMatchCase>], [<lDown>], [<lFromTop>], [<lListOnly>] ) ::FormatSource ( <lInteractive> )
Formats the layout of current source code (only for PRG files). <lInteractive> flag will cause the basic setup and confirmation dialog to be displayed prior to the formatting process. Displays the project function list dialog. Retrieves and jumps to the bookmark <nPos>, where <nPos> is 1-9. Any other value, eg. 0, or no value at all, means to jumps to the most recently edited spot. (see changes.txt for more details.) Returns text on line <nLine>, nLine defaults to the current line. If the <nLine> is not within the valid range, an empty string is returned.
::GetLine([<nLine>])
114
hbIDE
::GetScratchPad()
Opens the buffer nomination dialog, and replaces the currently selected text with the contents of the nominated scratch pad bufferIf not text is selected, the contents of the buffer is inserted at the curent cursor location. Returns the currently selected text. Returns the length of the entire file in bytes. Returns the word at current caret position ( optionally highlighting it ). Displays the Global search dialog. Places the caret at the last character in the file and scrolls it into view, if necessary. Attempts to place the caret on column <n>. Searches the list of project functions for the current word under cursor, and if found unique, jumps directly to that function, or displays a list of functions to choose from. Attempts to place the caret on line <n>. Optionally will attempt to stay on the current row,if <lKeepRow> is set to .T. (default .F.). Displays the GoTo Line dialog. Go to the temporary mark (if any). Places the caret on the first column of the first line and scrolls it into view, if necessary. Places the caret at the beginning of the line. Insert the prolog text at the top of the file (if the applicable prolog template file exists in the current profile folder). Inserts line <n>, and optionally sets <cText> text on the new line. Inverts the case of the selected text. Return .T. if at least part of the selection is displayed, otherwise it returns .F., if the selection is scrolled off screen. Set focus on the module function listbox. (only effective if the module function list is being displayed.) Attempts to move left <n> characters ( default 1 ). Obsolete method. See ::OffsetText(). Selects the next loaded file buffer. Jump to the next function (source code entity) Places the cursor at the beginning of the next word found. <cMask> is the strings of characters to skip at the beginning of the language element, (default is ' ')
::JumpToFuncList()
Public Methods
115
example: ::NextWord(" .^|(!") <lDumbSeek> if TRUE, will cause this method to disregard string and comment boundaries, default: FALSE. ::OffsetText( [<nCols>] ) Offsets the starting column of all the lines of the selected text to the left or to the right by <nCols> columns.(The default is ::TabSize.) Positive <nCols> value moves the selection to the right, and the negative one to the left.The selection columns are ignored and the entire lines are offset. If the selection is not present, the current line is processed. Either opens a specific file, if the parameter is a string, or it opens a list of editable project files for selection to add to the editor. Same as clicking on the "Open" toolbar button in the editor. The optional parameter <lNew> (default FALSE) requests a new file to be opened or created. If the parameter is a string, ie. <cFileName>, it may contain or consists of xMate variables. Opens the header selection interface dialog Places the caret on the bottom of the current page Moves down one page. Places the caret on top of the page. Moves up 1 page. Attempts to pan the display left by <n> columns. Attempts to pan the display to the right by <n> columns. Replaces the selected text with the text in the Windows clipboard, if present. Select the previous loaded file buffer. Jump to the previous function (source code entity) Places the cursor at the beginning of the previous word found. <cMask> is the strings of characters to skip at the beginning of the language element, (default is ' ') example: ::PrevWord(" .^|(!") <lDumbSeek> if TRUE, will cause this method to disregard string and comment boundaries, default: FALSE. High level wrapper for inserting text, and setting relative caret position. The relative caret position is calculated from the beginning of the inserted text. Retraces the undo operations See the editor configuration for undo setup options. Repaints the entire page. Repaints the current line. Updates the contents of the module function list.
::OpenFile([<lNew| cFileName>])
::OpenHeader() ::PageBottom() ::PageDown() ::PageTop() ::PageUp() ::PanLeft( <n> ) ::PanRight( <n> ) ::Paste() ::PrevEdit() ::PrevFunc() ::PrevWord( cMask, lDumb )
116
hbIDE
::ReplaceText( cFind, lMatchCase, lDown, cRepl, lGlobal, lNoPrompt ) ::ResetScratchPads() ::RestoreFromBackup () ::Right( [<n>] ) ::SaveCurrent() ::SaveFile ( [<lClearUndo>] ) ::ScrollDown( <n> ) ::ScrollUp( <n> ) ::SelectAll() ::SelectionGetLen() ::SelectionOff() ::SelectionOn ( <nLeft>, <nTop>, [<nRight>], [<nBottom>] ) ::SelEdit( <n> ) ::SetBookmark ( [<nPos>] )
Replaces the specified text, uses either the supplied parameters, or the last used method of searching. Clears and removes all scratch pad buffers, including the persistent buffers (1-9) Overwrite the current edit buffer with the most recent backup of the current file. Attempts to move right n characters ( default 1 ). Saves the current file. Saves the current file, and optionally clears the UNDO buffers. Attempts to scroll the display down by <n> lines. Attempts to scroll the display up by <n> lines. Select all text in the current buffer. Returns the length of the current selection in bytes. Clears the current selection, if any. Attempts to set selection at supplied coordinates.
Selects the <n>th file buffer loaded into the editor. Sets the bookmark <nPos> to the current line, where <nPos> is 1-9. Any other value, or no value at all, means to auto add a bookmark in the first available slot. (see changes.txt for more details.) Attempts to set the last visible line in the editor window, (<nLine> must be supplied). Sets the first visible column in the editor window, ( <nColumn> must be min. 1 ). Replaces the text on line <nLine> with <cText> Set or remove the temporary mark on the text line. If the <lSet> parameter is omitted, the mark is toggled. Otherwise the <lSet> flag instructs the method to either set or remove the mark. Note that the temporary mark is independent from the Bookmarks. Create a time stamped milestone of the current edit buffer. Opens the buffer nomination dialog, and sets the currently selected text in the nominated scratch pad buffer Sets the selection mode preference.
::SetMilestone() ::SetScratchPad()
Public Methods
117
Replaces the current selection with the supplied text. Sets the first visible line in the editor window, ( <nLine> must be min. 1 ). Shows or hides the editor feedback panel. If the parameter is omitted, the panel visibility is toggled Displays the list of user defined macros. Opens the code skeletons dialog. Finds and displays names of all accessible functions, methods and variables, which start with the word under cursor, eg. type str| and invoke this macro, all names starting with "str" will be displayed for selection. Sets the selected text into lower case. Capitalizes each word in the selected text. <cMask> is the string of characters to identify the beginning of the new word. (the default is ' '). Sets the selected text into upper case. Inserts the last deleted line at current position. Reverts the previous editing by one undo step. See the editor configuration for undo setup options. Return to the file and to the line in that file, from which the most recent jump to a function, to a search result, or an explicit move to a specified line was requested. Attempts to move up <n> lines, ( default 1 ).
::Up( [<n>] )
Part
XVIII
120
hbIDE
18
18.1
Part
XIX
122
hbIDE
19
Downloads
The distro of hbIDE under this page is scheduled to be updated with every major commit in the SVN. The revision number is always displayed in the titlebar of main window which you should mention while reporting a but or making a support call on the Harbour's devel-list. Please do not send any private email, I may not be in a position to respond to them. All support requests must be made on devel-list. Here is the maiden hbIDE (r14326) (ChangeLog: r14348) setup: hbIDE_10_14326
Part
XX
124
hbIDE
20
Part
XXI
126
hbIDE
21
hbQT
.cpp fileIs a wrappers library for binding Nokis's Qt ( a cross-platform GUI framework library ). It follows Qt's class hirarchy "as is" and encapsulate its objects in exactly the same way Qt does. We call it Harbour's Bindings for Qt and is named as hbQT - hb=Harbour Qt=Qt. It is comprised of two components, 1. .cpp compliant functions 2. .prg level Qt compliant class framework, the methods of which, call functions of ( 1 .cpp ). .cpp(s) are named after Qt's class name and contain the functions calling the methods of that class QWidget.cpp .prg files are named after .cpp file name but prefixed with "T" - TQWidget.prg
Part
XXII
128
hbIDE
22
hbXBP
Enter topic text here.
Part
XXIII
130
hbIDE
23
A thousand dollar question is - why GPF will appear for this very innocent code? qApp := QApplication():new() Simply because local variable oMB will go out of scope and GC will try to release its resources. s_events := It seems funny but the fact is it happens like this only. QT_EVENTS_NEW() s_slots := QT_SLOTS_NEW To trace down the flow of pointer's life cycle, this code must be compiled () with -nohbcppmm hbMK2 flag and including cppmmstub.cpp outlined below. Also place some trace calls in "delete" group of functions to qWnd := QMainWindow(): check if any of them is reached anytime. new() qWnd:setWindowTitle Function new( size_t nSize ) is always reached with every type of Qt ( "Harbour-Qt GC Diagram" ) object, but delete( void * ptr ) is reached by some of the Qt objects but qWnd:resize( 900, 500 ) even those inconsistently depending upon the program flow. qLabel := QLabel():new ( qWnd ) qLabel:setText( "Harbour" ) qLabel:move( 100, 100 ) qLabel:resize( 100, 50 ) qLabel:show() qBtn := QPushButton():new ( qWnd ) qBtn:setText( "Message Box" ) qBtn:move( 10, 10 )
2010 Pritpal Bedi
If an application is linked with -nohbcppmm then probbaly no GPF will be produced at all. In such case if a lot of objects will be created assigned to local variables, those will never be get released and memory usage will keep up growing.
131
qBtn:resize( 100, 30 ) Qt_Slots_Connect( s_slots, qBtn, "clicked()", ; {|| MyMessageBox( qWnd ) } ) qWnd:Show() qApp:exec() Qt_Slots_DisConnect ( s_slots, qBtn, "clicked()" ) RETURN
FUNCTION MyMessageBox ( qWnd ) LOCAL qMB qMB := QMessageBox():new ( qWnd ) qMB:setInformativeText ( "Harbour" ) qMB:setWindowTitle ( "Harbour-QT" ) qMB:exec() RETURN NIL /* cppstub.cpp */ #include "hbapi.h" const char * __hbmk2_hbcppmm( void ) { return "HBCPPMM"; } void operator delete[]( void * ptr ) { if( ptr ) { hb_xfree( ptr ); } } void operator delete[]( void * ptr, size_t ) { if( ptr ) { hb_xfree( ptr ); }
2010 Pritpal Bedi
132
hbIDE
} void operator delete( void * ptr ) { if( ptr ) { hb_xfree( ptr ); } } void operator delete( void * ptr, size_t nSize ) { if( ptr ) { hb_xfree( ptr ); } } void * operator new( size_t nSize ) { if( nSize == 0 ) { nSize = 1; } return hb_xgrab( nSize ); }
qMB := QMessageBox():new( qWnd ) void * hbqt_gcAllocate_QMessageBox( void * pObj, bool bNew ) { QGC_POINTER_QMessageBox * p = ( QGC_POINTER_QMessageBox * ) hb_gcAllocate( sizeof ( QGC_POINTER_QMessageBox ), hbqt_gcFuncs() ); p->ph = pObj; p->bNew = bNew; p->func = hbqt_gcRelease_QMessageBox; if( bNew ) { new( & p->pq ) QPointer< QMessageBox >( ( QMessageBox * ) pObj ); } return p; } HB_FUNC( QT_QMESSAGEBOX ) { void * pObj = NULL; pObj = ( QMessageBox* ) new QMessageBox() ; function - operator new( size_t nSize ) */ /* This call is routed to our overloaded
133
hb_retptrGC( hbqt_gcAllocate_QMessageBox( pObj, true ) ); } pPtr instance variable of qMB is now populated with GC collectible pointer. When the function will terminate, either pressing "X" on messagebox or clicking "Ok" button, GC will try to free oMB:pPtr and following function will be called: QT_G_FUNC( hbqt_gcRelease_QMessageBox ) { QGC_POINTER_QMessageBox * p = ( QGC_POINTER_QMessageBox * ) Cargo; if( p && p->bNew ) { if( p->ph && p->pq ) { const QMetaObject * m = ( ( QObject * ) p->ph )->metaObject(); if( ( QString ) m->className() != ( QString ) "QObject" ) { HB_TRACE( HB_TR_DEBUG, ( "YES_rel_QMessageBox /.\\ ph=%p pq=%p", p->ph, (void *)(p->pq) ) ); delete ( ( QMessageBox * ) p->ph ); /* We will always reach here and then will appear GPF */ /* because p->ph gets released by QT which is validated by p->pq becoming NULL */ /* but p->ph retains the value as is and hence GC tries to free it again which infact is already released */ /* Please note that all our checks to prevent it are intact to have a valid pointer but still... */ /* Infact, at this point Qt's own delete() operator is called ( and must be called ) as delete ( ( QMessageBox * ) ptr ) it would been defined in Qt headers */ HB_TRACE( HB_TR_DEBUG, ( "YES_rel_QMessageBox \\./ ph=%p pq=%p", p->ph, (void *)(p->pq) ) ); // This is never reached p->ph = NULL; } } } } This is simplest of the examples to trap GPF and its course and it does not use any of the other socalled "hacks" in hbQT implementation. Probably, Przemek can look into this deeply and can traceout the issue. If we do it here we will be very near the real issue. This will produce GPF on OS/2 for sure, or on certain other *nix systems. I am unable to get one on Windows XP and mingw 4.4.
Part
XXIV
136
hbIDE
24
24.1 24.2 24.3 24.4 24.5
Academics
Enter topic text here.
Software Space
Enter topic text here.
Contributions
Enter topic text here.
Achievements
Enter topic text here.
Index
137
Index
-BButton Panels 50
View
43
-OOutput Console 37
-P35 Project Functions Lookup 34 Project Properties Dialog Projects 30 Projects Tree 30 34
-CCompiler Environments
-TThemes Creating 36
-IIDE Help 32
138
hbIDE
Back Cover