Hbide - Manual Harbour Ide (en)

© 2010 Pritpal Bedi

Harbour's Integrated Development Environment

Introductionby Pritpal Bedi

hbIDE, as the name implies, Harbour's IntegratedDevelopment Environment, is an open-source, multi-platform,project hosted inside Harbour's SVN repository. hbIDE isaimed at simplifying the process of project life-cyclecomprising, setting-up the project components, editing thesources, building them to final binaries

All rights reserved. No parts of this work may be reproduced in any form or by any means - graphic, electronic, ormechanical, including photocopying, recording, taping, or information storage and retrieval systems - without thewritten permission of the publisher.

Products that are referred to in this document may be either trademarks and/or registered trademarks of therespective 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 noresponsibility for errors or omissions, or for damages resulting from the use of information contained in thisdocument or from the use of programs and source code that may accompany it. In no event shall the publisher andthe author be liable for any loss of profit or any other commercial damage caused or alleged to have been causeddirectly or indirectly by this document.

Printed: May 2010 in (whereever you are located)

hbIDE


PublisherSpecial thanks to:

Marcos Gambeta - who provided the first constructs to build Harbourwrappers.

Vik tor Szakats - who outlined the project goals and contributed thewhole of make system plus set right many weired parts.

Przemysaw Czerpak - who extended his valuable insight as to thecourse of structure to base library.

Vailton Renato - for implementing build system and providing tons ofimages.

Bisz Istvan - who introduced the extended constructs for garbagecollection.

Francesco Parillo - who became instrument to find and set right thelong-hogging bug in cooeration with Bisz Istvan.

Massimo Belgrano - for continually pushing for the project andask ing new features.

Antonio Maniero - for setting wight some artifacts from usabilitypoint of view.

And all users - who tested, debugged and provided valuable info,tips, comments, to set right which went the wrong direction.

Managing Editor

Technical Editors

Cover Designer

http://www.harbour-project.org

Pritpal Bedi

Pritpal Bedi

Pritpal Bedi

Production

Pritpal Bedi

Team Coordinator

Vik tor Szakats

5Contents

5


Table of Contents

Foreword 9

Part I Introduction 12

Part II The Origin 14

................................................................................................................................... 151 And as of now

Part III Symantics 20

................................................................................................................................... 201 The Build

................................................................................................................................... 202 Technical Sheet

Part IV A Visual Tour 24

................................................................................................................................... 241 First Timer

................................................................................................................................... 262 Only Editor

................................................................................................................................... 303 With Left Panel Docks

................................................................................................................................... 324 With Right Panel Docks

................................................................................................................................... 375 With Bottom Docks

................................................................................................................................... 386 And Bare-boned

Part V Understanding Interface 40

................................................................................................................................... 401 Title Bar

................................................................................................................................... 412 Menu Bar

................................................................................................................................... 443 Toolbar - Top

................................................................................................................................... 504 Toolbar - Left

................................................................................................................................... 515 Toolbar - Right

................................................................................................................................... 526 Status Bar

................................................................................................................................... 537 Projects Tree

................................................................................................................................... 538 Editor Tabs Tree

................................................................................................................................... 549 Skeletons Tree

................................................................................................................................... 5410 Editing Area

................................................................................................................................... 5511 hbIDE Help

................................................................................................................................... 5612 Documentation Viewer

................................................................................................................................... 5713 Documentation Writer

................................................................................................................................... 5814 Functions List

................................................................................................................................... 5915 Projects Functions List

................................................................................................................................... 6016 Project Properties

................................................................................................................................... 6117 Compiler Environments

................................................................................................................................... 6218 Code Skeletons

hbIDE6


................................................................................................................................... 6319 Theme Manager

................................................................................................................................... 6420 Find in Files

................................................................................................................................... 6521 Output Console

Part VI Book Marks 68

Part VII Panels 70

Part VIII Sources 72

................................................................................................................................... 721 Loading

................................................................................................................................... 722 Creating

................................................................................................................................... 723 Editing

.......................................................................................................................................................... 72Intellisense

Part IX Projects 76

................................................................................................................................... 781 Loading

................................................................................................................................... 792 Creating

................................................................................................................................... 843 Building

................................................................................................................................... 844 Compiler Environments

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

................................................................................................................................... 1081 Understanding Interface

.......................................................................................................................................................... 108Toolbar Navigation

.......................................................................................................................................................... 108Documents Tree

......................................................................................................................................................... 108Contents Tab

......................................................................................................................................................... 108Index Tab

......................................................................................................................................................... 108Category Tab

.......................................................................................................................................................... 108Document Viewer

......................................................................................................................................................... 108View

......................................................................................................................................................... 108Write

................................................................................................................................... 1082 Navigate Topics

Part XVI Themes 110

Part XVII Public Methods 112

7Contents

7


Part XVIII Thanks and Credits 120

................................................................................................................................... 1201 The Harbour Crew

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

................................................................................................................................... 1361 Academics

................................................................................................................................... 1362 Software Space

................................................................................................................................... 1363 Contributions

................................................................................................................................... 1364 Achievements

................................................................................................................................... 1365 You may skip...

Index 137

Foreword

Dedicated to my wife anddaughters who spared me ofsome duties which led me to

allocate more time to thisproject.

9Foreword


Part

I

hbIDE12


1 Introduction

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 ofproject life-cycle comprising, setting-up the project components, editing the sources, building them tofinal binaries.

Currently, only Harbour as a compiler is supported, and hopefully soon, its domain will be extended toxHarbour, Xbase++, Clipper, Clip, Flagship.

The central essense of hbIDE is to provide a single-window interface to carry on all related actions for anapplication project to materialize, without needing any other tool in the process. This concept isextended 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 themas 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 ownproduction projects is presented below.

Part

II

hbIDE14


2 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 availablefor 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 hadnumerous talks about its features. Since then xMate is an integral part of my development cycles. Iam 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 agreat amount of time is not invested into it. As of now I do not have requirements to convert myapplications 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 ofmy 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.

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 thiseffort, not only for coding but also for debugging, suggestions and whatever... So I see in optimismfor 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 singleinstance.Implements: tracking the compile/link errors and opening the source containing thus error in theeditor 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 auto-indentation; 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 tolower, invert cases; line operations: duplicating a line, deletion of line, moving lined in eitherdirection - up/down; and many more.

hbIDE16


Implements: splitting one edit instance into multiple horizontal and/or vertical windows to editdifferent parts of the same source simultaneously.Implements: auto-disaster-recovery for every editing instance per minute interval ensuring themaximum amount of loss confined to a minute's work only.Implements: code-skeleton definition and rendering to next levels with user-defined macros andvariables 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-spotfunction prototype tips, full-blown function overlook, and more.Implements: a powerful "Find-in-files" feature accepting currently-opened edits, containedprojects, folders on the disk including sub-folders, options for plain-text or regular expressionsearch, and finally opening the source with currently clicked search-text highlighted in theeditor.Implements: a unique "Document Viewer" which pulls the NANFORUM documentation formatcompliant .txt files from a "root folder" and tree and presents the contents in a navigable browserwith options to - "Print", "Save as .pdf", and more.Implements: a unique way to write documentation for functions contained in the editing sessionswith options to insert the same into the source at appropriate place or save as a NANFORUMdocumentation 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 provisionto set the highlighting themes in the hands of the user as per needs and offering a bunch of pre-defined themes plus interface to inject your own.Implements: intelligent "book-marks" with visual elements to define, locate and destroy - withleast 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 detachedmanner. Probably it will be wise to extend it to accept parameters comprised of properties ofhbIDE 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 exactsame environment at next run, including the editors state per cursor position, the size andposition of the main frame, and lot more.Implements: an interface to define short-cut macros just like xMate plus including someextended functionality. Implements: three types of selection modes: 1. Stream Selection 2. Column Selection 3. LineSelection. All type of blocks are persistent across files. Stream selection mode is a standardtext selection protocol implemented by every text editor in the world. Column selection hassome peculiar application and Line selection mode offer yet another functionality. All types offerstandard cut/copy/paste behavior. Paste operation honors the selection mode, f.e., a blockselected under column mode will be pasted as column block. Line blocks overwrite the exitinglines if pasted.Implemented: a simple yet powerful interface to hook third-party plugins designating it truelyextensible.

What is proposed

Visual debugger - someone has to jump in as I know a little about debuggers and their behaviorForm 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-linecommands.

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 toughscripts to achieve high levels of productivity.An all-in-one, composite-components oriented, highly desktop real-estate conscious interfaceleveraging 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 Clanguage.

Pitfalls

High memory-intensive back-bone.

Part

III

hbIDE20


3 Symantics

This section describes various facts about hbIDE as a whole.

The BuildHow to Initiate

3.1 The Build

hbIDE is a complete PRG level OO ( class code ) implementation and is based on mixed calls to hbXBPand 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 approachhas been adopted from the fact that Xbase++ class framework is much limited as compared to thepower of Qt classes that not all can be encapsulated in hbXBP unless it is extended to include classesmatching that of Qt. It is already planned to enhance hbXBP framework beyond what Alaska offers inXbase++, 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 newcomers, so I briefly describe below what these two libraries are all about.

hbQTIs a wrappers library for binding Nokis's Qt ( http://qt.nokia.com/ ), a cross-platform GUI frameworklibrary. It follows Qt's class hirarchy "as is" and encapsulate its objects in exactly the same way Qtdoes. We call it - Harbour's Bindings for Qt and is named as hbQT - hb=Harbour Qt=Qt. It is comprisedof two components,

1. .cpp compliant functions2. .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.

hbXBPIs a class framework 100% based on Alaska's Xbase++ ( www.alaska-software.com ) and call hbQT'sclass-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 withmulti-platform support ) without any changes whatsoever. To some extent hbXBP has been successful indoing so. I am sure, it will absorb Xbase++ code completely in coming future. It is just a matter of timewhich 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 algorithmis 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 startuppanel, no project tree will be displayed.

ExamplesC:\harbour\contrib\hbide>hbide.exe hbide.hbpC:\harbour\contrib\hbide>hbide.exe idemisc.prg idethemes.prgC:\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 ofhbIDE.

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

hbIDE24


4 A Visual Tour

This section will contain the screen shots making the viewer familiar with the interface and judging itscapabilities on the surface levels.

You are, however, encouraged to study deeply the next topic Understanding interface.

These screens are included here under:

First TimerOnly EditorWith Left Panel DocksWith Right Panel DocksWith Bottom DocksAnd Bare-boned

4.1 First Timer

First time hbIDE is invoked after installation:

After splash screen disappears:

A Visual Tour 25


After clicking the "FAQ" tab:

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

hbIDE26


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

down:

A Visual Tour 27


After invoking context menu with right-click:

After positioning the cursor at line 342 and clicking "Toggle Mark" icon in the top-toolbar and navigating down

to line 348:

After "Splitting" the editor horizontally via "Split..." option of context menu:

hbIDE28


After switching off the line-numbers display by clicking "Toggle Line Numbers" icon on left-toolbar:

After switching off the split w indow from context menu, also keeping line numbers switched off:

A Visual Tour 29


After switching-on the line numbers and and applying a new theme "Evening Glamour" to current editor via

context menu:

Next: Left Docking Panes

hbIDE30


4.3 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"

A Visual Tour 31


Next: With Right Panel Docks

hbIDE32


4.4 With Right Panel Docks

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

After clicking "Harbour Documentation" icon on the right-toolbar:

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

A Visual Tour 33


After clicking on "Documentation Writer" icon on right-toolbar:

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

hbIDE34


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 "Compiler Environments" icon on the right-toolbar and retaining tooltip while hovering over

blank edit box:

After clicking "Code Skeletons" icon on right-toolbar, (luckily I had few skeletons defined already which are

visible inside, though it w ill be blank first time):

hbIDE36


After clicking "Theme Manager" on right-toolbar, the height is automatically expanded a little because of

many controls in it:

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

A Visual Tour 37


Next: With Bottom Docks

4.5 With Bottom Docks

After clicking "Output Console" icon on right-toolbar:

hbIDE38


Next: And Bare-boned

4.6 And Bare-boned

After hiding all left and right toolbars and line numbers display - as simple as could be:

Next: Understanding Interface

Part

V

hbIDE40


5 Understanding Interface

This section will explain the various parts of the user-interface and their relation to each other. Theunderstanding 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 demonstrateinterface 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 BarMenu BarTop ToolbarLeft ToolbarRight ToolbarStatusbar

5.1 Title Bar

The various components of hbIDE's title-bar can be best grasped as under

Understanding Interface 41


Next: Main Menu Bar

5.2 Menu Bar

hbIDE's main menu bar contains following entries:

Menu Bar

<Files>

hbIDE42


<Edit>

<Projects>



<Build>

<Setup>

<View>

hbIDE44


<Help>

5.3 Toolbar - Top

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

.



Below we enumerate the various buttons on the Main Toolbar.

Button Invokes Alternate ShortcutPublic

MethodDescription

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

Ctrl+Sh+W Unlike "X"button, thisaction doesnot ask forconfirmationwhether userreally wantsto exit.

Panel: Stats Hosts twotabs:

1. Welcome,displayingstatistics forhostedprojectswithdrill-downfeature.

2. FAQ's,providinganswers tosomeFAQ's

New editor instancewith title "Untitled" onthe active panel.

MenuBar->Files->New->Source

Ctrl+N At thisinvocation nosyntaxhighlightingtheme isassigned tothe source.It is theresponsibility of the userto save itwith validextensionand then

hbIDE46


reopen thesame tohave themeactivated.

File Open Dialog toselect a source to beedited.

MenuBar->Files->Open Ctrl+O The selectedfile is testedagainsthbIDE'ssupportedformats andan alert isissued if itdoes notmatches andoperation isabandoned.

Saves the activeediting instancesource on the disk.

MenuBar->Files->Save Ctrl+S The saveoperation issilent, noalert isissued.

Closes the activeediting instance.

MenuBar->Files->Close Ctrl+WEsc

If theinstance isin "Modified"state thanan alert isissued toconfirm if itbe savedfirst beforeclosing.

Print Preview Dialogwith active editinginstance contents.

Ctrl+P Print Previewdialog offersa variety ofoptions fromcontrolledprinting toexport tovariousformats,such asPDF.

Compiles activeediting instance if it isa .prg source.

Context-menu->Compile

Compiles activeediting instance to .ppo format if it is .prgsource.

MenuBar->Build-Compile toPPOContext-menu->Compile toPPO

If compilesucceeds,opens .ppointo a neweditinginstance.



Builds the "current"project.

MenuBar->Build->BuildProject

If no projectis set as"current" ( can beconfirmedfrom status-bar panel ),a list ofhostedprojects ispresented toselect one. If somesource fromthis projectis opened inany of theeditinginstances,and is in a"Modified"state, thenthus sourceis savedbefore"Build"processstarts.

Thisexplanationholds goodfor nextthreeoptions.

Builds current projectand Launches it ifsuccessful.

MenuBar->Build->Build andLaunch

Re-Builds the currentproject.

MenuBar->Build->Re-buildProject

Re-Builds the currentproject and Launchesit if successful

MenuBar->Build->Re-buildand Launch

Undo one recent editoperation.

MenuBar->Edit->UndoContext-menu.

Ctrl+Z Undo andnext 11options areeditingactionswhich arealwayscarried on

hbIDE48


active editinstance orsplit.

Redo one recentundone edit operation

MenuBar->Edit->RedoContext-menu.

Ctrl+R This shortcutcannot beover-ridden.

Cuts the selected textif any.

MenuBar->Edit->CutContext-menu.

Del

Copies selected textonto clipboard

MenuBar->Edit->CopyContext-menu.

Ctrl+C This shortcutcannot beover-ridden.

Pastes the clipboardtext at current cursorposition.

MenuBar->Edit->PasteContext-menu.

Ctrl+V This shortcutcannot beover-ridden.

Selects the entirecontents of active editinstance.

MenuBar->Edit->Select All Ctrl+A This shortcutcannot beover-ridden.

Flags if currentselection mode isstream or columns.

At presentonly stream-selection isavailable. Iam workinghard to getcolumn-selectionworking andwill beavailablesome-time infuture.

Invokes Search &Replace Dialog

MenuBar->Edit->Find /Replace

Ctrl+F

Toggles a bookmarkon the current line.

A visualrepresentation of thebookmark isplaced as acoloredrectangle atthe left ofline-numbersdisplay areaand the lineis alsopainted withsame colorasbackground.The line



color ispersistentand isbrought tonoticewhenever thesegment ofsourcecontaining itis navigatedto viewport ofthe editinginstance.

Acorresponding button ona panel instatus-baralso appearswith samecolor as thatof markerandfacilitates tojump to thatparticularbookmarklinewheneverclicked.

In all, oneeditinginstance canhave 6bookmarksmaximum atany givenmoment.

Goto Line Dialog MenuBar->Edit->Goto Line Ctrl+G

Zooms-In the text withlarger fonts.

Note thatthere is noway ofreturningback tooriginal font.The onlyway toachieve so is

hbIDE50


either closethe instanceand openagain or re-run hbIDE.

Zooms-Out the textwith smaller fonts.

Tools & Utilities Dlg.DnArrow: drop-downmenu to invoke a Tool.

Creates or brings anexisting panel to front.

Though youare free tocreate nnumber ofpanels, butstill takecare of left-toolbarsbeingoverburdened.

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 ofactions specific to lines and block selections. The "Panels" toolbar is expected to grow downwardscorresponding the number of panels.

Toolb

ar

Butto

nInvokes Alternate Shortcut

Public

MethodDescription

Editor Panel"Main"

Top-Toolbar"Panels Icons"sDrop-down Menu

Current LineDown

Main Menu->Edit->Line->CurrentLine Down

Ctrl+Sh+Dn

Current LineUp

Main Menu->Edit->Line->CurrentLine Up

Ctrl+Sh+Up

DeleteCurrent Line

Main Menu->Edit->Line->DeleteCurrent Line

Ctrl+Del

DuplicateCurrent Line

Main Menu->Edit->Line->DuplicateCurrent Line

Ctrl+D



Toggles LineNumbersDisplay

Button's depressed state denotes thatline numbers display is off. This toggleis valid for all editor instances and thesetting is remembered for next run.

Converts toUpper Case

Converts toLower Case

Inverts Case

Single LineComment

Main Menu->Edit->Block->SingleLine Comment

Ctrl+Sh+/

StreamComment

Main Menu->Edit->Block->StreamComment

Ctrl+Sh+Q

Indents OneColumn Right

Main Menu->Edit->Block->IndentRight

Ctrl+Tab

Indents OneColumn Left

Main Menu->Edit->Block->IndentLeft

Ctrl+Sh+Tab

SingleQuotes toDouble

Main Menu->Edit->Block->SingleQuotes to Double

DoubleQuotes toSingle

Main Menu->Edit->Block->DoubleQuotes to Single

5.5 Toolbar - Right

Right toolbar is specific to toggling the docking widgets hosted at left, right, or bottom areas of the mainwindow. 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 separatedfrom 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 putbehind 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 nextrun. However these widgets will be opened at the last saved state if invoked.

Tool

bar

Butto

nsInvokes

Docking

AreaAttributes Alternate Other Links

hbIDE52


Project Tree Left Non-Detachable

Main Menu->View->Projects

Editors Tree Left Non-Detachable

Main Menu->View->Editors

SkeletonsTree

Left Non-Detachable

Main Menu->View->Skeletons

hbIDE Help Right Detachable Main Menu->View->hbIDEHelp

DocumentViewer

Right Detachable Main Menu->View->HarbourDocumentation

DocumentWriter

Right Detachable Main Menu->View->Documentation Writer

FunctionsList

Right Detachable Main Menu->View->Functions List

Project(s)FunctionsList

Right Detachable Main Menu->View->ProjectsFunctions Lookup

ProjectProperties

Right Detachable Main Menu->View->ProjectProperties

CompilerEnvironments

Right Detachable Main Menu->View->CompilerEnvironments

CodeSkeletons

Right Detachable Main Menu->View->CodeSkeletons

ThemeManager

Right Detachable Main Menu->View->ThemeManager

Find-inFilesManager

Right Detachable Main Menu->View->Find inFiles

OutputConsole

Bottom Non-Detachable

Main Menu->View->OutputConsole

See Also:Main Menu->View

5.6 Status Bar

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



5.7 Projects Tree

Projects tree depicts the projects hosted inside for current session. It also provides the interface toCreate, Load, Build and various other actions associated with projects and the source files comprisingthose projects.

Projects tree is a left-side docking widget and has an attribute to hide or show, resize, etc. This settingis remembered for subsequent run. It exposes standard navigational behavior, viz., left-click: selectsnode, 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.

hbIDE54


5.9 Skeletons Tree

Code snippets or skeletons are implemented in a powerful way in hbIDE. One of the major feature of thisimplementation 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 editinginstances.

It can be termed as epic-center of hbIDE. All other components are ancillary to the working of hbIDE.



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 ornot. However, for beginners, this may provide some food for thought in their own applications.

hbIDE56


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.



5.13 Documentation Writer

Documentation writer is a unque-to-hbIDE interface which provides the necessary constructs to includedocumentation right along the function body or separately on the disk confirming to NANFORUMdocumentation standards.

hbIDE58


5.14 Functions List

Functions List presents all the functions contained in the source open in current active editor instanceand provides a convenient way to reach to any one by double-clicking on its node in the list.



5.15 Projects Functions List

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

hbIDE60


5.16 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.

hbIDE62


5.18 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 forsyntax-highlighting.

hbIDE64


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.



5.21 Output Console

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

hbIDE66


Part

VI

hbIDE68


6 Book Marks

Enter topic text here.

Part

VII

hbIDE70


7 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 hoststwo tabs - 1. Welcome and 2. FAQ's

2. Editors: is of variable number. Panel named "Main" is always present and cannot be removed. nnumber of other panels can be created by user.

Part

VIII

hbIDE72


8 Sources


8.1 Loading


8.2 Creating


8.3 Editing


8.3.1 Intellisense

hbIDE implements the concept of "intellisense" in a unique way. The concepts employed are not said tobe "exhaustive" but provide a fair degree of guidance to the developer. The concepts are a mix oftraditional 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 ofcombinations.Click on "Re-Tag" button, if this is the first time you are tagging project(s), or "LoadTags" 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 ProjectSource.Type some alphabets in the top-most edit control. It will position the function matchingthe 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 exercisecarried above. The moment you will type "(" a nicelyformatted tooltip, displying the prototype of this function will appear beneth the caretposition. The prototype will remain there for 10 seconds ( finding a way how it can becontrolled the way I want ).Position editor caret somewhere in some function characters and activate context menuwith right click. Select "Goto Function" option.It will open the underlying source withcursor positioned on the function proto. Siultaneously, the function will be made currentin the table in "Projects Functions Lookup" widget.

Sources 73


Part

IX

hbIDE76


9 Projects

At present hbIDE supports projects specific to Harbour as compiler. However any language dialect canuse it for organizing the projects and editing tasks taking use of hbIDE's powerful interface. Hopefullysoon, support for following languages will be implemented, strictly in the order given below:

1. xHarbour2. Xbase++3. Clipper4. Clip5. Flagship

Interface elements relevant to a project:

<Project option on Main Menu>

<Build option on Main Menu>

<Compile and Build options in Top-Toolbar>

Projects 77


<Project Tree holding various projects>

<Context menu on Project Name node of Project

Tree>

<Welcome page displaying contained projects w ith

Stats>

hbIDE78


<Project Detail on Welcome>

<Project Build Output>

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 hbIDERight-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.

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 andthen make changes to confirm to your workings ]

Edit contents loaded from this file in the editor to suit paths to different compilers to matchyour 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 anEnvironment..." and select one from the popup menu.Thus selected environment should be visible in "Env:" panel of status-bar and remain valid forany 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:

.

hbIDE80


Projects 81


hbIDE82


Projects 83


hbIDE84


9.3 Building


9.4 Compiler Environments

hbIDE implements everything-in-one approach to define C compilers configurations. The file which storesthus settings is hbide.env. The interface implements a slot to hold the path to this file. By default it issearched where hbde.ini is loaded.

A Pictorial Overview

Projects 85


The contents in this file may look like this ( this is from my production environment - 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} set HB_INSTALL_PREFIX=C:\harbour_dev\harbour\mingw{content} set HB_INC_INSTALL=C:\harbour_dev\harbour\mingw\include{content} set HB_LIB_INSTALL=C:\harbour_dev\harbour\mingw\lib{content} set 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

hbIDE86


[ 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 isdisplayed in the status-bar on selection.

{hbmk2} is the placeholder for parameters passed to hbMK2 directly on the command line. hbMK2accepts two types of parameters; 1.included in the .hbp; 2. passed on the command line. For moredetails please read INSTALL. So this placeholder is the only way to pass command-line parametershbMK2 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 isexecuted prior to invoking hbMK2.

"#" - hash is the only comments delimiter and must be specified as the first character on a new linefollowed by comments line.

All the environments defined as above are included in the context-menu. Last environment selected isretained 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 thesame instance of hbIDE. Just change the environment from context-menu and compile. If you haveprovided the right kind of flags to hbMK2, chances are your projects will be build fine in first attempt. Iuse it extensively. Take use of it.

But the is not mandatory. You can still build your projects if you invoke hbIDE from console which isalready configured for a compiler. In the absence of selection from context-menu, default environmentprevailing is used.

Part

X

hbIDE88


10 Keyboard Mappings

hbIDE provides an interface similar to xMate to define keyboard shortcuts where each shortcut may be abig 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

hbIDE92


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

hbIDE94


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

Code Snippets 95


/*------------------------------*/

METHOD MyNewClass:create( oIde )

DEFAULT oIde TO ::oIde ::oIde := oIde

RETURN Self

/*------------------------------*/

Part

XII

hbIDE98


12 Tools and Utilities

hbIDE employs a unique feature of executing external processes, attached or detached. Tools engine isimplements almost on top of "Project Building" protocol and supports the similar functionality in additionto traditional one. This means through this you are capable of build any project of any language yet notsupported by hbIDE. Infact it widens the scope of hbIDE usage. Below is the Tools & Utilities dialog andthe explanation of its fields followed by examples and other facts.

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 issearched 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 besearched by clicking on <Browse> button. This is the application which will be invoked witha click on <Execute> button or clicking on drop-down menu of. If left blank, it will invoke

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 <CommandLine>. If no application is defined then this field will be considered as application(s) withparameters. This field is subject to path normalization and hence character "/" and "\" willbe treated as path separators. Normalization is not applied if "http://" is a part of this field. Itimplied that "/" must not be used for command line arguments. You are encouraged to usehiphen "-" instead of slash "/" for this purpose.

Start In: placeholder the path which will be made current before invoking the application. Ithelps in fine-tuning the behavior if some environment is dependent on fixed locations for anycomponents.

Capture Output: placeholder to flag if the tool defined herein is invoked as "attached" to thisprocess and is subject to capture the standard and errors output ? If switched ON, thebehavior of this utility will correspond to one which is employed for "building" a project, withsame features as to tracking the link/compile errors. This opens up the possibilities toexecute edit/compile/link cycle for n number of languages and compiler for which hbIDEdoes 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" isalso checked. This feature is especially useful in cases when we are invoking files whichare associated to some other application but we do not want to see the shell commandwindow. 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 openedin an edit tab. We are supplying source name with the full qualifiedpath and are not caring for from where it is invoked. The otheralternative could be: <Parameters> hbide.prg <Start In> 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 theoutput window from where you can reach to the offending line bydouble clicking, much like if an Harbour project has been built.

Command Line

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

hbIDE100


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 ). <cName> is the name of the tool and must be already definedbefore calling, otherwise no action will take place.

2. ::execTool( cCommand, cParams, cStartIn, lCapture, lOpenOutputConsole ) if called likethis it does not look for any pre-defined definition. If none of the parameters is supplied, ashell command window will be invoked.

Part

XIII

hbIDE102


13 Plugins

The concept of "Plugins" is quiet old and all the major tools provide some interface to hook third-party plugins to extend the domain of such tool. hbIDE also provides such interface. Below is theinitial 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.

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 ==========================

hbIDE104


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

hbIDE106


14 Documentation Writer

It is a quick way to generate help. You can keep the documentation in your sources or can create a treelike Harbour's. I know there is a lot more to be done in this tool, but at least group can start using it.

1. Click on "Documentation Writer" icon on the right-toolbar, 2. Open some source in the editor, 3. Position cursor somewhere inside a function body, 4. 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

hbIDE108


15 Documentation Viewer


15.1 Understanding Interface


15.1.1 Toolbar Navigation


15.1.2 Documents Tree


15.1.2.1 Contents Tab


15.1.2.2 Index Tab


15.1.2.3 Category Tab


15.1.3 Document Viewer


15.1.3.1 View


15.1.3.2 Write


15.2 Navigate Topics


Part

XVI

hbIDE110


16 Themes

The concept of Themes in hbIDE is synonymous to syntax-highlighting rules rather than applicationtheme. hbIDE provides an xMate like interface to change, add, apply, save themes. It also provides forapplying the themes to individual editing instance level.

Part

XVII

hbIDE112


17 Public Methods

hbIDE is scheduled to implement some methods which may be called from user-defined macros insidethe editing instances through shortcuts or menu options. Soon this protocol will be in the SVN. To keepmyself and upto-date of what "should be" and "has been" implemented, here is the list of such methodswhich I think should make-up the bunch.

Please note that these methods are along the lines of xMate and initial list below includes all methodscontained in xMate v1.15.

MethodStat

us

Curr

entDescription Links

::AlignOperator() Aligns the assignment operators within the top andthe bottom of the current selection. Columnselection provides for special features.

"OperAlign.txt"

::AppendScratchPad() Opens the buffer nomination dialog, and appendsthe currently selected text to the nominatedscratch pad buffer

::AutoComplete() Auto-completes the initiated key. "complete.txt"

::Backup() Creates the backup file See the editorconfiguration for backup file extension options.

::BeginUndo() Starts buffering the operations that follow, into asingle undo step. Also see the EndUndo() method.

::Build([<lRebuild>]) Saves all updated files and builds ( makes ) theapplication. The optional <lRebuild> flag will causethe complete rebuild of the project.

::BuildAndRun([<lRebuild>])

Saves all updated files and builds ( makes ) theapplication. The application is launched, if the buildas successful. The optional <lRebuild> flag willcause 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(<lComment>)

Adds, or removes comment indicator "//" from thebeginning of the selected lines of text.

::CompileCurrent() Compiles the current file.

::CompileToPPO() Creates the PPO output from the current file, ifapplicable.

::Copy() Copies selected text into the Windows clipboard

::Cut() Deletes the selected text, and places it in theWindows clipboard.

::DelLine( [<n>] ) Deletes line <n>. The default line is the currentline.NOTE that the complete macro for deleting a lineshould read:

Public Methods 113


::DelLine(::line), IF(::Line > ::Lines, ::Up(), NIL), .F.

::DelRest() Deletes the reminder of the line.

::DelScratchPad() Opens the buffer nomination dialog, and deletesthe nominated scratch pad buffer

::DelText() Deletes the selected text.

::DelWordRest([<cOperators>])

Deletes characters till the end of the word.Distinguishes [<cOperators>] from the regularalphanumerical characters, as separate words.The default <cOperators> are: '<>,.?/';:\|{}[]=-+()&&*% #̂$!@~`" .

::Down( [<n>] ) Attempts to move down <n> lines ( default 1 ).

::DupLine() Duplicates the current line, by inserting it directlybelow the current line.

::End() Places the caret at the end of the current line.

::EndUndo() Submits the editing steps for examination to theundo engine, to create a single undo step. Alsosee the BeginUndo() method.

::Expand() Clears summary mode, and places the caret at thebeginning of the currently highlighted function.

::FindDlg([<lUseWordUnderCursor>],[<lAutoMode>],[<lListOnly>])

Displays the search and replace dialog. Theoptional parameters are: lUseWordUnderCursor - set to TRUE to paste theword under cursor (default) lAutoMode - set to TRUE to let the dialog set thesearch mode automatically (default) lListOnly - set to TRUE to turn on the resultlisting.

::FindMatch() Finds the matching bracket to the one at thecurrent caret position.

::FindNext() Atempts to continue the most recent search.

::FindText( <cFind>,[<lMatchCase>],[<lDown>],[<lFromTop>],[<lListOnly>] )

Finds the specified text, uses either the suppliedparameters, or the last used method of searching.

::FormatSource( <lInteractive> )

Formats the layout of current source code (only forPRG files). <lInteractive> flag will cause the basicsetup and confirmation dialog to be displayed priorto the formatting process.

::FuncInfoDlg() Displays the project function list dialog.

::GetBookmark( [<nPos>] )

Retrieves and jumps to the bookmark <nPos>,where <nPos> is 1-9. Any other value, eg. 0, or novalue at all, means to jumps to the most recentlyedited spot. (see changes.txt for more details.)

::GetLine([<nLine>]) Returns text on line <nLine>, nLine defaults to thecurrent line. If the <nLine> is not within the validrange, an empty string is returned.

hbIDE114


::GetScratchPad() Opens the buffer nomination dialog, and replacesthe currently selected text with the contents of thenominated scratch pad bufferIf not text is selected,the contents of the buffer is inserted at the curentcursor location.

::GetText() Returns the currently selected text.

::GetTextLen() Returns the length of the entire file in bytes.

::GetWord( [<lHilite>] ) 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 fileand scrolls it into view, if necessary.

::GoToCol( <n> ) Attempts to place the caret on column <n>.

::GoToFunc() Searches the list of project functions for thecurrent word under cursor, and if found unique,jumps directly to that function, or displays a list offunctions to choose from.

::GoToLine( <n>,[<lKeepRow>] )

Attempts to place the caret on line <n>. Optionallywill attempt to stay on the current row,if<lKeepRow> 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 lineand scrolls it into view, if necessary.

::Home( [<lUnconditional>] )

Places the caret at the beginning of the line.

::InsertProlog() Insert the prolog text at the top of the file (if theapplicable prolog template file exists in the currentprofile folder).

::InsLine( <n>,[<cText>] )

Inserts line <n>, and optionally sets <cText> texton the new line.

::InvertCase() Inverts the case of the selected text.

::isSelectionVisible() Return .T. if at least part of the selection isdisplayed, otherwise it returns .F., if the selectionis scrolled off screen.

::JumpToFuncList() Set focus on the module function listbox. (onlyeffective if the module function list is beingdisplayed.)

::Left( [<n>] ) Attempts to move left <n> characters ( default 1 ).

::MoveText( [<nCols>] )

Obsolete method. See ::OffsetText().

::NextEdit() Selects the next loaded file buffer.

::NextFunc() Jump to the next function (source code entity)

::NextWord( [<cMask>],[<lDumb>] )

Places the cursor at the beginning of the next wordfound.<cMask> is the strings of characters to skip at thebeginning of the language element, (default is ' ')

Public Methods 115


example: ::NextWord(" . |̂(!")<lDumbSeek> if TRUE, will cause this method todisregard string and comment boundaries, default:FALSE.

::OffsetText( [<nCols>])

Offsets the starting column of all the lines of theselected 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 selectioncolumns are ignored and the entire lines are offset.If the selection is not present, the current line isprocessed.

::OpenFile([<lNew|cFileName>])

Either opens a specific file, if the parameter is astring, or it opens a list of editable project files forselection to add to the editor. Same as clicking onthe "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>, itmay 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( <n> ) Attempts to pan the display left by <n> columns.

::PanRight( <n> ) Attempts to pan the display to the right by <n>columns.

::Paste() Replaces the selected text with the text in theWindows 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 previousword found.<cMask> is the strings of characters to skip at thebeginning of the language element, (default is ' ')example: ::PrevWord(" . |̂(!")<lDumbSeek> if TRUE, will cause this method todisregard string and comment boundaries, default:FALSE.

::PutText( <cText>,<nLine>, <nCol> )

High level wrapper for inserting text, and settingrelative caret position. The relative caret position iscalculated from the beginning of the inserted text.

::ReDo() Retraces the undo operations See the editorconfiguration for undo setup options.

::RefreshAll() Repaints the entire page.

::RefreshCurrent() Repaints the current line.

::RefreshFuncList() Updates the contents of the module function list.

hbIDE116


::ReplaceText( cFind,lMatchCase, lDown,cRepl, lGlobal,lNoPrompt )

Replaces the specified text, uses either thesupplied parameters, or the last used method ofsearching.

::ResetScratchPads() Clears and removes all scratch pad buffers,including the persistent buffers (1-9)

::RestoreFromBackup()

Overwrite the current edit buffer with the mostrecent backup of the current file.

::Right( [<n>] ) Attempts to move right n characters ( default 1 ).

::SaveCurrent() Saves the current file.

::SaveFile( [<lClearUndo>] )

Saves the current file, and optionally clears theUNDO buffers.

::ScrollDown( <n> ) Attempts to scroll the display down by <n> lines.

::ScrollUp( <n> ) Attempts to scroll the display up by <n> lines.

::SelectAll() Select all text in the current buffer.

::SelectionGetLen() Returns the length of the current selection inbytes.

::SelectionOff() Clears the current selection, if any.

::SelectionOn( <nLeft>, <nTop>,[<nRight>],[<nBottom>] )

Attempts to set selection at supplied coordinates.

::SelEdit( <n> ) Selects the <n>th file buffer loaded into the editor.

::SetBookmark( [<nPos>] )

Sets the bookmark <nPos> to the current line,where <nPos> is 1-9. Any other value, or no valueat all, means to auto add a bookmark in the firstavailable slot. (see changes.txt for more details.)

::SetBottomLine( <nLine> )

Attempts to set the last visible line in the editorwindow, (<nLine> must be supplied).

::SetLeftCol( <nColumn> )

Sets the first visible column in the editor window,( <nColumn> must be min. 1 ).

::SetLine( <nLine>,<cText> )

Replaces the text on line <nLine> with <cText>

::SetMark([<lSet>]) Set or remove the temporary mark on the text line.If the <lSet> parameter is omitted, the mark istoggled. Otherwise the <lSet> flag instructs themethod to either set or remove the mark. Note thatthe temporary mark is independent from theBookmarks.

::SetMilestone() Create a time stamped milestone of the currentedit buffer.

::SetScratchPad() Opens the buffer nomination dialog, and sets thecurrently selected text in the nominated scratchpad buffer

::SetSelectionMode( <lByColumn>,[<lFullLine>] )

Sets the selection mode preference.

Public Methods 117


::SetText( <cText> ) Replaces the current selection with the suppliedtext.

::SetTopLine( <nLine> )

Sets the first visible line in the editor window,( <nLine> must be min. 1 ).

::ShowFeedbackPanel([<lShow>])

Shows or hides the editor feedback panel. If theparameter 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 accessiblefunctions, methods and variables, which start withthe word under cursor, eg. type str| and invoke thismacro, all names starting with "str" will bedisplayed for selection.

::ToLower() Sets the selected text into lower case.

::ToTitle( [<cMask>] ) Capitalizes each word in the selected text.<cMask> is the string of characters to identify thebeginning 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. Seethe editor configuration for undo setup options.

::UnJump() Return to the file and to the line in that file, fromwhich the most recent jump to a function, to asearch result, or an explicit move to a specifiedline was requested.

::Up( [<n>] ) Attempts to move up <n> lines, ( default 1 ).

hbIDE Defined Methods

::execTool( ... ) Executes an entry in the "Tools and Utilities"collection as

::execTool( cName ) or can be used directly ( without entry in the Toolsmenu ) as

::execTool( cCmd, cParams, cStartIn,lCapture, lOpenOutputConsole )

Part

XVIII

hbIDE120


18 Thanks and Credits


18.1 The Harbour Crew


Part

XIX

hbIDE122


19 Downloads

The distro of hbIDE under this page is scheduled to be updated with every major commit in the SVN. Therevision number is always displayed in the titlebar of main window which you should mention whilereporting 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 supportrequests must be made on devel-list.

Here is the maiden hbIDE (r14326) (ChangeLog: r14348) setup:

hbIDE_10_14326

Part

XX

hbIDE124


20 The Other Links

This section familiarize you with some links which might be useful to Xbase dialect programmers, mainlydescendants 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/

Part

XXI

hbIDE126


21 hbQT

.cpp fileIs a wrappers library for binding Nokis's Qt ( a cross-platform GUI framework library ). It followsQt'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 twocomponents,

1. .cpp compliant functions2. .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

hbIDE128


22 hbXBP


Part

XXIII

hbIDE130


23 hbQT - GC - Qt Object Destruction

In this section I will try to explain the foundations of hbQT, its variables life-cycle, Harbour GC interactionand 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 apointer has been released by Qt. This has been all the more difficult because of the fact that Qt does notrespect its own documentation where it states that if "new" and "delete" operators are overloaded by theapplication, the calls to obtain and free the pointers will be routed to application defined operatorsinstead of Qt's own.

Strange fact is this that, "new" operator is always routed to Harbour's but "delete" operators behavior isinconsistent. Few objects are passes back to application's "delete" whereas most are not. I will try toexplain hereunder how the things are moving inside these two nodes.

Let's start with a bare minimum example:

REQUEST HB_QT

STATIC s_eventsSTATIC s_slots

PROCEDURE Main() Local qApp, qWnd, qLabel,qBtn

qApp := QApplication():new()

s_events :=QT_EVENTS_NEW() s_slots := QT_SLOTS_NEW()

qWnd := QMainWindow():new() qWnd:setWindowTitle( "Harbour-Qt GC Diagram" ) qWnd:resize( 900, 500 )

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 )

In this example I will concentrate on function MyMessageBox() whichwhen invoked by clicking on push button should produce a GPF onmany systems with astonishingly different behavior with different Ccompilers and Qt's releases. If some event happens in a predictableway, it is subject to resolution sooner or later, but what if same isexperienced by somebody and just passes away some others.

A thousand dollar question is - why GPF will appear for this veryinnocent code?Simply because local variable oMB will go out of scope and GC will tryto release its resources.It seems funny but the fact is it happens like this only.

To trace down the flow of pointer's life cycle, this code must be compiledwith -nohbcppmm hbMK2 flag and including cppmmstub.cpp outlinedbelow. Also place some trace calls in "delete" group of functions tocheck if any of them is reached anytime.

Function new( size_t nSize ) is always reached with every type of Qtobject, but delete( void * ptr ) is reached by some of the Qt objects buteven those inconsistently depending upon the program flow.

If an application is linked with -nohbcppmm then probbaly no GPF will beproduced at all. In such case if a lot of objects will be created assignedto local variables, those will never be get released and memory usagewill keep up growing.

hbQT - GC - Qt Object Destruction 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 ); }

hbIDE132


}

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() ; /* This call is routed to our overloadedfunction - operator new( size_t nSize ) */

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 tryto 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 appearGPF */ /* because p->ph gets released by QT which isvalidated by p->pq becoming NULL */ /* but p->ph retains the value as is and hence GCtries to free it again which infact is already released */ /* Please note that all our checks to prevent it areintact 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 so-called "hacks" in hbQT implementation.Probably, Przemek can look into this deeply and can traceout the issue. If we do it here we will be verynear the real issue. This will produce GPF on OS/2 for sure, or on certain other *nix systems. I amunable to get one on Windows XP and mingw 4.4.

Part

XXIV

hbIDE136


24 Meet the Author


24.1 Academics


24.2 Software Space


24.3 Contributions


24.4 Achievements


24.5 You may skip...


Index 137


Index- B -Button

Panels 50

- C -Compiler Environments 35

- D -Document Viewer 32

Document Writer 33

- E -Editors Tree 30

execTool

method 117

- F -Find-in-files Dialog

File search 36

Find 36

Search 36

Functions List 33

- I -IDE Help 32

- M -Menu

Build 43

Edit 42

Files 41

Help 44

Projects 42

Setup 43

View 43

- O -Output Console 37

- P -Project Functions

Lookup 34

Project Properties Dialog 34

Projects 30

Projects Tree 30

- S -Skeletons

Creating 35

Skeletons Tree 30

- T -Themes

Creating 36

Endnotes 2... (after index)

hbIDE138


Back Cover

Hbide - Manual Harbour Ide (en)

Documents

harbourdevharbourmingwbin

hbharbour

harbourcontribhbidegt

xbase dialect

buffer nomination

qt object

copies selected

source code