Hbide - Manual Harbour Ide (en)

Harbour's Integrated Development Environment © 2010 Pritpal Bedi

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

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.

Pritpal Bedi Team Coordinator Vik tor Szak ats Production Pritpal Bedi

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

5

Table of Contents Foreword

9

Part I Introduction

12

Part II The Origin

14

1 And as ................................................................................................................................... of now 15

Part III Symantics

20

1 The Build ................................................................................................................................... 20 2 Technical ................................................................................................................................... Sheet 20

Part IV A Visual Tour

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

Part V Understanding Interface

40

1 Title Bar ................................................................................................................................... 40 2 Menu................................................................................................................................... Bar 41 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 ................................................................................................................................... Skeletons 62 © 2010 Pritpal Bedi

5

6

hbIDE 19 Theme ................................................................................................................................... Manager 63 20 Find in ................................................................................................................................... Files 64 21 Output ................................................................................................................................... Console 65

Part VI Book Marks

68

Part VII Panels

70

Part VIII Sources

72

1 Loading ................................................................................................................................... 72 2 Creating ................................................................................................................................... 72 3 Editing ................................................................................................................................... 72 Intellisense .......................................................................................................................................................... 72

Part IX Projects

76

1 Loading ................................................................................................................................... 78 2 Creating ................................................................................................................................... 79 3 Building ................................................................................................................................... 84 4 Compiler ................................................................................................................................... Environments 84

Part X Keyboard Mappings

88

Part XI Code Snippets

92

Part XII Tools and Utilities

98

Part XIII Plugins

102

Part XIV Documentation Writer

106

Part XV Documentation Viewer

108

1 Understanding ................................................................................................................................... Interface 108 Toolbar Navigation .......................................................................................................................................................... 108 Docum ents Tree .......................................................................................................................................................... 108 Contents ......................................................................................................................................................... Tab 108 Index Tab......................................................................................................................................................... 108 Category ......................................................................................................................................................... Tab 108 Docum ent View .......................................................................................................................................................... er 108 View ......................................................................................................................................................... 108 Write ......................................................................................................................................................... 108

2 Navigate ................................................................................................................................... Topics 108

Part XVI Themes

110

Part XVII Public Methods

112 © 2010 Pritpal Bedi

Contents

Part XVIII Thanks and Credits

7

120

1 The ................................................................................................................................... Harbour Crew 120

Part XIX Downloads

122

Part XX The Other Links

124

Part XXI hbQT

126

Part XXII hbXBP

128

Part XXIII hbQT - GC - Qt Object Destruction

130

Part XXIV Meet the Author

136

1 Academics ................................................................................................................................... 136 2 Software ................................................................................................................................... Space 136 3 Contributions ................................................................................................................................... 136 4 Achievements ................................................................................................................................... 136 5 You ................................................................................................................................... may skip... 136

Index

137

© 2010 Pritpal Bedi

7

Foreword

Foreword

Dedicated to my wife and daughters who spared me of some duties which led me to allocate more time to this project.


9

Part

I

12

1

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

2

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

3

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

4

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:

After splash screen disappears:


A Visual Tour

After clicking the "FAQ" tab:

After clicking on the round "Panels: Main" icon on top of left-toolbar:


25

26

hbIDE

Next: Only Editor

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 invoking context m enu w ith right-click:

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:

Next: Left Docking Panes


30

4.3

hbIDE

With Left Panel Docks After clicking the "Projects" icon on the right-toolbar and resizing the "Projects" tree w idget a little:

After clicking "Editors" icon on the right-toolbar:

After clicking "Skeletons Tree" © 2010 Pritpal Bedi

A Visual Tour

Next: With Right Panel Docks


31

32

4.4

hbIDE

With Right Panel Docks After clicking "hbIDE Help" icon on the right-toolbar and sizing the w idth a little:

After clicking "Harbour Docum entation" icon on the right-toolbar:

After providing the "Harbour Installation Root:" and searching "ascan" under "Index" tab:


A Visual Tour

After clicking on "Docum entation Writer" icon on right-toolbar:

After clicking on "Functions List" icon on right-toolbar:


33

34

hbIDE

After clicking on "Projects Functions Lookup" icon on right-toolbar:

After clicking on "Project's Properties" icon on right-toolbar:


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:

After clicking "Find in Files" icon on the right-toolbar:


A Visual Tour

Next: With Bottom Docks

4.5

With Bottom Docks After clicking "Output Console" icon on right-toolbar:


37

38

hbIDE

Next: And Bare-boned

4.6

And Bare-boned After hiding all left and right toolbars and line num bers display - as sim ple as could be:

Next: Understanding Interface


Part

V

40

5

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

Next: Main Menu Bar

5.2

Menu Bar hbIDE's main menu bar contains following entries:

Menu Bar


41

42

hbIDE




43

44

hbIDE

5.3

Toolbar - Top This section describes the different elements of hbIDE's top-toolbar.

.



45

Below we enumerate the various buttons on the Main Toolbar. Button

Invokes

Exits hbIDE

Alternate

Main Menu->Files->Exit "X" button on Title-bar

Shortcut

Ctrl+Sh+W

Panel: Stats

New editor instance MenuBar->Files->Newwith title "Untitled" on >Source the active panel.


Public Method

Description

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

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.

Saves the active editing instance source on the disk.

MenuBar->Files->Save

Ctrl+S

The save operation is silent, no alert is issued.

Closes the active editing instance.

MenuBar->Files->Close

Ctrl+W Esc

If the instance is in "Modified" state than an alert is issued to confirm if it be saved first before closing.

Ctrl+P

Print Preview dialog offers a variety of options from controlled printing to export to various formats, such as PDF.

Print Preview Dialog with active editing instance contents.

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.



Builds the "current" project.

MenuBar->Build->Build Project

47

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.

Ctrl+R

This shortcut cannot be over-ridden.

Del

Copies selected text onto clipboard

MenuBar->Edit->Copy Context-menu.

Ctrl+C


Pastes the clipboard text at current cursor position.

MenuBar->Edit->Paste Context-menu.

Ctrl+V


Ctrl+A


Selects the entire MenuBar->Edit->Select All contents of active edit instance. Flags if current selection mode is stream or columns.

Invokes Search & Replace Dialog Toggles a bookmark on the current line.

At present only streamselection is available. I am working hard to get columnselection working and will be available some-time in future. 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



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.

5.4

Though you are free to create n number of panels, but still take care of lefttoolbars being overburdene d.

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

Editor Panel "Main"

Top-Toolbar "Panels Icons"s Drop-down Menu

Current Line Down

Main Menu->Edit- Ctrl+Sh >Line->Current +Dn Line Down

Current Line Up

Main Menu->Edit- Ctrl+Sh >Line->Current +Up Line Up

Delete Current Line

Main Menu->Edit- Ctrl+Del >Line->Delete Current Line

Duplicate Current Line

Main Menu->Edit- Ctrl+D >Line->Duplicate Current Line

Public Method

Description



Toggles Line Numbers Display

51

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.

Converts to Upper Case Converts to Lower Case Inverts Case Single Line Comment

Main Menu->Edit- Ctrl+Sh >Block->Single +/ Line Comment

Stream Comment

Main Menu->Edit- Ctrl+Sh >Block->Stream +Q Comment

Indents One Main Menu->Edit- Ctrl+Ta Column Right >Block->Indent b Right

5.5

Indents One Column Left

Main Menu->Edit- Ctrl+Sh >Block->Indent +Tab Left

Single Quotes to Double

Main Menu->Edit>Block->Single Quotes to Double

Double Quotes to Single

Main Menu->Edit>Block->Double Quotes to Single

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.

Tool Butto bar ns


Invokes

Docking Area

Attributes

Alternate

Other Links

52

hbIDE

Project Tree

Left

NonMain Menu->View->Projects Detachable

Editors Tree

Left

NonMain Menu->View->Editors Detachable

Skeletons Tree

Left

NonMain Menu->ViewDetachable >Skeletons

hbIDE Help

Right

Detachable Main Menu->View->hbIDE Help

Document Viewer

Right

Detachable Main Menu->View->Harbour Documentation

Document Writer

Right

Detachable Main Menu->View>Documentation Writer

Functions List

Right

Detachable Main Menu->View>Functions List

Project(s) Functions List

Right

Detachable Main Menu->View->Projects Functions Lookup

Project Properties

Right

Detachable Main Menu->View->Project Properties

Compiler Environments

Right

Detachable Main Menu->View->Compiler Environments

Code Skeletons

Right

Detachable Main Menu->View->Code Skeletons

Theme Manager

Right

Detachable Main Menu->View->Theme Manager

Find-inFiles Manager

Right

Detachable Main Menu->View->Find in Files

Bottom

NonMain Menu->View->Output Detachable Console

Output Console

See Also: Main Menu->View

5.6

Status Bar This section describes various panels of status-bar and explains the contents therein.



5.7

53

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

Editor Tabs Tree Editors tree exposes a visual navigation to reach an editor instance hosted on any of the panels.


54

5.9

hbIDE

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.



5.11

55

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

5.12

hbIDE

Documentation Viewer Documentation Viewer provides an hbIDE-unique feature to view Harbour and/or own documentation (NANFORUM compliant format) in an interlinked GUI environment.



5.13

57

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

5.14

hbIDE

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.



5.15

59

Projects Functions List Projects Functions List provides a searchable functions lookup for n number of projects together. Thus n numbers are user dependant and are memorized for next run of hbIDE.


60

5.16

hbIDE

Project Properties Project Properties dialog is the epic-center of complete project management.



5.17

Compiler Environments Environment settings plays an important role if hbIDE is used to build projects.


61

62

5.18

hbIDE

Code Skeletons Code skeletons, if defined properly, is a powerful way to reduce development time.



5.19

Theme Manager Theme manager lets you control the look and feel of editor instances plus allows to define rules for syntax-highlighting.


63

64

5.20

hbIDE

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.



5.21

Output Console Output Console is the placeholder for all compile/link generated output, standard or error.


65

66

hbIDE


Part

VI

68

6

hbIDE

Book Marks Enter topic text here.


Part

VII

70

7

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

8

hbIDE

Sources Enter topic text here.

8.1

Loading Enter topic text here.

8.2

Creating Enter topic text here.

8.3

Editing Enter topic text here.

8.3.1

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

9

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

Interface elements relevant to a project:


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

9.3

hbIDE

Building Enter topic text here.

9.4

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

{content} set HB_COMPILE_SINGLE_SOURCE=yes {content} set HB_TR_SYSOUT=yes {content} set HB_WITH_QT=C:\qt\4.6.2\qt

[ 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

X

88

10

hbIDE

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

11

hbIDE

Code Snippets

How to write ========= * Click main-menu option and select . * "Code Skeletons" window will open at the right-docking area. * Close other docks if open to make room for its components. * Click 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 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 . * Repeat the process for some other skeletons. * Do not forget to click 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 , follow next process. Click to save permanently. * 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 . * 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..." © 2010 Pritpal Bedi Code Snippets 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 93 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 /*------------------------------*/ METHOD MyNewClass:create( oIde ) DEFAULT oIde TO ::oIde ::oIde := oIde RETURN Self /*------------------------------*/ © 2010 Pritpal Bedi 95 Part XII 98 12 hbIDE Tools and Utilities hbIDE employs a unique feature of executing external processes, attached or detached. Tools engine is implements almost on top of "Project Building" protocol and supports the similar functionality in addition to traditional one. This means through this you are capable of build any project of any language yet not supported by hbIDE. Infact it widens the scope of hbIDE usage. Below is the Tools & Utilities dialog and the explanation of its fields followed by examples and other facts. How to Invoke Clicking the button on top-toolbar brings up above dialog. Clicking on drop-down menu of button's down-arrow invokes the selected tool. Fields Name: can be provided manually or will be pulled from if an application is searched with by clicking on . 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 button. This is the application which will be invoked with a click on button or clicking on drop-down menu of. If left blank, it will invoke © 2010 Pritpal Bedi Tools and Utilities 99 shell command. This field is subject to normalization of path. Parameters: placeholder for arguments to be supplied to application defined in . 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: hbide.prg C:/harbour/ contrib/hbide/. Command Line C:/harbour/contrib/hbide/hbide.exe Parameters C:/harbour/contrib/hbide/hbide.prg Start In Capture Output Open Output 2 Name 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. Command Line © 2010 Pritpal Bedi Parameters C:/batches/xp_env/alaska90.bat && xpp -q C:/harbour/tests/speedtst.prg && alink speedtst Start In C:/harbour/tests Capture Output Yes Open Output Yes 100 hbIDE 3 Name Command Prompt : opens a DOS console window. Command Line cmd.exe Parameters Start In Capture Output Open Output 4 Name http : opens up this page in the browser. Command Line Parameters start http://hbide.vouch.info/tools_and_utilities.htm Start In Capture Output Yes Open Output Public Method hbIDE provides two ways to call a tool as its public methods API. 1. ::execTool( 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. © 2010 Pritpal Bedi Part XIII 102 13 hbIDE 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 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 ========================== © 2010 Pritpal Bedi 103 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. © 2010 Pritpal Bedi Part XIV 106 14 hbIDE 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. © 2010 Pritpal Bedi Part XV 108 15 hbIDE Documentation Viewer Enter topic text here. 15.1 Understanding Interface Enter topic text here. 15.1.1 Toolbar Navigation Enter topic text here. 15.1.2 Documents Tree Enter topic text here. 15.1.2.1 Contents Tab Enter topic text here. 15.1.2.2 Index Tab Enter topic text here. 15.1.2.3 Category Tab Enter topic text here. 15.1.3 Document Viewer Enter topic text here. 15.1.3.1 View Enter topic text here. 15.1.3.2 Write Enter topic text here. 15.2 Navigate Topics Enter topic text here. © 2010 Pritpal Bedi Part XVI 110 16 hbIDE 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. © 2010 Pritpal Bedi Part XVII 112 17 hbIDE 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. ::AppendScratchPad() Opens the buffer nomination dialog, and appends the currently selected text to the nominated scratch pad buffer ::AutoComplete() Auto-completes the initiated key. ::Backup() Creates the backup file See the editor configuration for backup file extension options. ::BeginUndo() Starts buffering the operations that follow, into a single undo step. Also see the EndUndo() method. ::Build([]) Saves all updated files and builds ( makes ) the application. The optional flag will cause the complete rebuild of the project. ::BuildAndRun ([]) Saves all updated files and builds ( makes ) the application. The application is launched, if the build as successful. The optional flag will cause the complete rebuild of the project. ::ClearUndo() Clears the Undo buffers. ::CloseAll() Closes all files and exits the editor window. ::CloseCurrent() Closes the current file. ::CodeSkeletonsDlg() Displays the code skeletons selection dialog. ::Collapse() Places the editor into function summary mode. ::Comment () Adds, or removes comment indicator "//" from the beginning of the selected lines of text. ::CompileCurrent() Compiles the current file. ::CompileToPPO() Creates the PPO output from the current file, if applicable. ::Copy() Copies selected text into the Windows clipboard ::Cut() Deletes the selected text, and places it in the Windows clipboard. ::DelLine( [] ) Deletes line . The default line is the current line. NOTE that the complete macro for deleting a line should read: "complete.txt" © 2010 Pritpal Bedi Public Methods ::DelLine(::line), IF(::Line > ::Lines, ::Up(), NIL), . F. ::DelRest() Deletes the reminder of the line. ::DelScratchPad() Opens the buffer nomination dialog, and deletes the nominated scratch pad buffer ::DelText() Deletes the selected text. ::DelWordRest ([]) Deletes characters till the end of the word. Distinguishes [] from the regular alphanumerical characters, as separate words. The default are: '<>,.?/';:\|{}[]=-+() &&*%^#$!@~`" . ::Down( [] ) Attempts to move down lines ( default 1 ). ::DupLine() Duplicates the current line, by inserting it directly below the current line. ::End() Places the caret at the end of the current line. ::EndUndo() Submits the editing steps for examination to the undo engine, to create a single undo step. Also see the BeginUndo() method. ::Expand() Clears summary mode, and places the caret at the beginning of the currently highlighted function. ::FindDlg ([],[], []) 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. ::FindMatch() Finds the matching bracket to the one at the current caret position. ::FindNext() Atempts to continue the most recent search. ::FindText( , [], [], [], [] ) Finds the specified text, uses either the supplied parameters, or the last used method of searching. ::FormatSource ( ) Formats the layout of current source code (only for PRG files). flag will cause the basic setup and confirmation dialog to be displayed prior to the formatting process. ::FuncInfoDlg() Displays the project function list dialog. ::GetBookmark ( [] ) Retrieves and jumps to the bookmark , where 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.) ::GetLine([]) Returns text on line , nLine defaults to the current line. If the is not within the valid range, an empty string is returned. © 2010 Pritpal Bedi 113 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. ::GetText() Returns the currently selected text. ::GetTextLen() Returns the length of the entire file in bytes. ::GetWord( [] ) Returns the word at current caret position ( optionally highlighting it ). ::GlobalSearchDlg() Displays the Global search dialog. ::GoBottom() Places the caret at the last character in the file and scrolls it into view, if necessary. ::GoToCol( ) Attempts to place the caret on column . ::GoToFunc() 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. ::GoToLine( , [] ) Attempts to place the caret on line . Optionally will attempt to stay on the current row,if is set to .T. (default .F.). ::GoToLineDlg() Displays the GoTo Line dialog. ::GotoMark() Go to the temporary mark (if any). ::GoTop() Places the caret on the first column of the first line and scrolls it into view, if necessary. ::Home ( [] ) Places the caret at the beginning of the line. ::InsertProlog() Insert the prolog text at the top of the file (if the applicable prolog template file exists in the current profile folder). ::InsLine( , [] ) Inserts line , and optionally sets text on the new line. ::InvertCase() Inverts the case of the selected text. ::isSelectionVisible() Return .T. if at least part of the selection is displayed, otherwise it returns .F., if the selection is scrolled off screen. ::JumpToFuncList() Set focus on the module function listbox. (only effective if the module function list is being displayed.) ::Left( [] ) Attempts to move left characters ( default 1 ). ::MoveText ( [] ) Obsolete method. See ::OffsetText(). ::NextEdit() Selects the next loaded file buffer. ::NextFunc() Jump to the next function (source code entity) ::NextWord ( [], [] ) Places the cursor at the beginning of the next word found. is the strings of characters to skip at the beginning of the language element, (default is ' ') © 2010 Pritpal Bedi Public Methods example: ::NextWord(" .^|(!") if TRUE, will cause this method to disregard string and comment boundaries, default: FALSE. ::OffsetText( [] ) Offsets the starting column of all the lines of the selected text to the left or to the right by columns.(The default is ::TabSize.) Positive 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. ::OpenFile([]) 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 (default FALSE) requests a new file to be opened or created. If the parameter is a string, ie. , it may contain or consists of xMate variables. ::OpenHeader() Opens the header selection interface dialog ::PageBottom() Places the caret on the bottom of the current page ::PageDown() Moves down one page. ::PageTop() Places the caret on top of the page. ::PageUp() Moves up 1 page. ::PanLeft( ) Attempts to pan the display left by columns. ::PanRight( ) Attempts to pan the display to the right by columns. ::Paste() Replaces the selected text with the text in the Windows clipboard, if present. ::PrevEdit() Select the previous loaded file buffer. ::PrevFunc() Jump to the previous function (source code entity) ::PrevWord( cMask, lDumb ) Places the cursor at the beginning of the previous word found. is the strings of characters to skip at the beginning of the language element, (default is ' ') example: ::PrevWord(" .^|(!") if TRUE, will cause this method to disregard string and comment boundaries, default: FALSE. ::PutText( , , ) High level wrapper for inserting text, and setting relative caret position. The relative caret position is calculated from the beginning of the inserted text. ::ReDo() Retraces the undo operations See the editor configuration for undo setup options. ::RefreshAll() Repaints the entire page. ::RefreshCurrent() Repaints the current line. ::RefreshFuncList() Updates the contents of the module function list. © 2010 Pritpal Bedi 115 116 hbIDE ::ReplaceText( cFind, lMatchCase, lDown, cRepl, lGlobal, lNoPrompt ) Replaces the specified text, uses either the supplied parameters, or the last used method of searching. ::ResetScratchPads() Clears and removes all scratch pad buffers, including the persistent buffers (1-9) ::RestoreFromBackup () Overwrite the current edit buffer with the most recent backup of the current file. ::Right( [] ) Attempts to move right n characters ( default 1 ). ::SaveCurrent() Saves the current file. ::SaveFile ( [] ) Saves the current file, and optionally clears the UNDO buffers. ::ScrollDown( ) Attempts to scroll the display down by lines. ::ScrollUp( ) Attempts to scroll the display up by lines. ::SelectAll() Select all text in the current buffer. ::SelectionGetLen() Returns the length of the current selection in bytes. ::SelectionOff() Clears the current selection, if any. ::SelectionOn ( , , [], [] ) Attempts to set selection at supplied coordinates. ::SelEdit( ) Selects the th file buffer loaded into the editor. ::SetBookmark ( [] ) Sets the bookmark to the current line, where 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.) ::SetBottomLine ( ) Attempts to set the last visible line in the editor window, ( must be supplied). ::SetLeftCol ( ) Sets the first visible column in the editor window, ( must be min. 1 ). ::SetLine( , ) Replaces the text on line with ::SetMark([]) Set or remove the temporary mark on the text line. If the parameter is omitted, the mark is toggled. Otherwise the flag instructs the method to either set or remove the mark. Note that the temporary mark is independent from the Bookmarks. ::SetMilestone() Create a time stamped milestone of the current edit buffer. ::SetScratchPad() Opens the buffer nomination dialog, and sets the currently selected text in the nominated scratch pad buffer ::SetSelectionMode ( , [] ) Sets the selection mode preference. © 2010 Pritpal Bedi Public Methods ::SetText( ) Replaces the current selection with the supplied text. ::SetTopLine ( ) Sets the first visible line in the editor window, ( must be min. 1 ). ::ShowFeedbackPanel ([]) Shows or hides the editor feedback panel. If the parameter is omitted, the panel visibility is toggled ::ShowHelp() Displays the list of user defined macros. ::Skeletons() Opens the code skeletons dialog. ::SpellHelp() 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. ::ToLower() Sets the selected text into lower case. ::ToTitle( [] ) Capitalizes each word in the selected text. is the string of characters to identify the beginning of the new word. (the default is ' '). ::ToUpper() Sets the selected text into upper case. ::UnDelLine() Inserts the last deleted line at current position. ::Undo() Reverts the previous editing by one undo step. See the editor configuration for undo setup options. ::UnJump() 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. ::Up( [] ) Attempts to move up lines, ( default 1 ). hbIDE Defined Methods ::execTool( ... ) © 2010 Pritpal Bedi Executes an entry in the "Tools and Utilities" collection as ::execTool( cName ) or can be used directly ( without entry in the Tools menu ) as ::execTool( cCmd, cParams, cStartIn, lCapture, lOpenOutputConsole ) 117 Part XVIII 120 18 hbIDE Thanks and Credits Enter topic text here. 18.1 The Harbour Crew Enter topic text here. © 2010 Pritpal Bedi Part XIX 122 19 hbIDE 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 © 2010 Pritpal Bedi Part XX 124 20 hbIDE The Other Links This section familiarize you with some links which might be useful to Xbase dialect programmers, mainly descendants from Clipper age and have adopted or trying to adopt Harbour as their language of choice. . http://www.harbour-project.org/ http://n2.nabble.com/harbour-devel-f1590103.html http://cch4clipper.blogspot.com/ © 2010 Pritpal Bedi Part XXI 126 21 hbIDE 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 © 2010 Pritpal Bedi Part XXII 128 22 hbIDE hbXBP Enter topic text here. © 2010 Pritpal Bedi Part XXIII 130 23 hbIDE hbQT - GC - Qt Object Destruction In this section I will try to explain the foundations of hbQT, its variables life-cycle, Harbour GC interaction and Qt's own destruction mechanism. As you all know, we are struggling to balance the Harbour GC behavior and Qt's object destruction, which, at times involves the same pointer. We have not been able to locate how GC should know when a pointer has been released by Qt. This has been all the more difficult because of the fact that Qt does not respect its own documentation where it states that if "new" and "delete" operators are overloaded by the application, the calls to obtain and free the pointers will be routed to application defined operators instead of Qt's own. Strange fact is this that, "new" operator is always routed to Harbour's but "delete" operators behavior is inconsistent. Few objects are passes back to application's "delete" whereas most are not. I will try to explain hereunder how the things are moving inside these two nodes. Let's start with a bare minimum example: REQUEST HB_QT STATIC s_events STATIC s_slots PROCEDURE Main() Local qApp, qWnd, qLabel, qBtn In this example I will concentrate on function MyMessageBox() which when invoked by clicking on push button should produce a GPF on many systems with astonishingly different behavior with different C compilers and Qt's releases. If some event happens in a predictable way, it is subject to resolution sooner or later, but what if same is experienced by somebody and just passes away some others. 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() 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. qBtn := QPushButton():new ( qWnd ) qBtn:setText( "Message Box" ) qBtn:move( 10, 10 ) © 2010 Pritpal Bedi hbQT - GC - Qt Object Destruction 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 131 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 © 2010 Pritpal Bedi hbQT - GC - Qt Object Destruction 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. © 2010 Pritpal Bedi Part XXIV 136 24 hbIDE Meet the Author Enter topic text here. 24.1 Academics Enter topic text here. 24.2 Software Space Enter topic text here. 24.3 Contributions Enter topic text here. 24.4 Achievements Enter topic text here. 24.5 You may skip... Enter topic text here. © 2010 Pritpal Bedi Index View Index -O- -BButton Panels Output Console Compiler Environments -DDocument Viewer Document Writer 32 33 -E30 117 -FFind-in-files Dialog File search 36 Find 36 Search 36 Functions List 33 -IIDE Help 32 -MMenu Build 43 Edit 42 Files 41 Help 44 Projects 42 Setup 43 © 2010 Pritpal Bedi 37 -P- 50 -C- Editors Tree execTool method 43 35 Project Functions Lookup 34 Project Properties Dialog Projects 30 Projects Tree 30 -SSkeletons Creating 35 Skeletons Tree 30 -TThemes Creating 36 34 137 138 hbIDE Endnotes 2... (after index) © 2010 Pritpal Bedi Back Cover

Hbide - Manual Harbour Ide (en)

Recommend Documents