nx_Controls Programmer’s Guide

 

Contents:

 

Introduction: 3

nx_Controls Design Principles and Philosophy. 3

Description of nx_Control classes. 4

Class: nx_Frame. 5

Description: 5

Methods: 5

Class: nx_Panel 5

Description: 5

Methods: 5

Class: nx_Notebook. 6

Description: 6

Methods: 6

Class: nx_Group. 6

Description: 6

Methods: 6

Class: nx_Control 6

Description: 6

Methods: 6

Class: nx_Button. 7

Description: 7

Methods: 7

Class: nx_CheckBox. 7

Description: 7

Methods: 7

Class: nx_TextCtrl 8

Description: 8

Methods: 8

Class: nx_Slider 8

Description: 8

Methods: 8

Class: nx_SpinCtrl 8

Description: 8

Methods: 9

Class: nx_ListBox. 9

Description: 9

Methods: 9

Class: nx_ListCtrl 9

Description: 9

Methods: 10

Class: nx_ComboBox. 10

Description: 10

Methods: 10

Class: nx_Menu. 10

Description: 10

Methods: 10

Class: nx_MenuItem.. 11

Description: 11

Methods: 11

 


Introduction:

nx_Controls is a limited set of classes that represent a number of GUI elements.  The range of elements will be extended over time.  At present the nx_Controls are wrapper classes for the far more extensive wxWindows library of classes.  If you are not familiar with the wxWindows class library you are encouraged to study it first before attempting to use nx_Controls. 

 

The nx_Controls introduce the following key coding concepts and functionality:

·        Child objects are added to their parent using the insertion operator (ie. <<)  Each child is responsible for being inserted and taking care of such things as IDs etc.

·        Each control type has a default event type

·        Event functions are attached using the objects constructor

·        Output from one GUI element (eg. a listbox) can be automatically channelled (piped) to another (eg. a textctrl).

 

It is also highly recommended that time is taken to review the source code of the nx_Controls sample application – as many questions are answered once it is understood how the classes are intended to be used.  It is also recommended the source code for the sister project, nxNet is studied as this will show how the nx_Controls approach works in a real and moderately complex application.

 

The nx_Controls project is still very much a ‘proof of concept’.  Feedback and suggestions regarding the approach are most welcome.

nx_Controls Design Principles and Philosophy

The development of the nx_Controls set of classes is driven by the desire to reduce the level of tedious detail that the programmer typically has to contend with when constructing the user interface for an application.  The following principles have been used to guide the development – although some are yet to be fully realised.

 

  1. An object oriented approach to GUI design should not require the programmer to be responsible for low level mechanics (eg. ensuring a unique ID for every menuitem or button control).
  2. An object oriented design philosophy should encourage the programmer to focus on the relationship between components and their relationship to the application as a whole.
  3. Rather than attempting to offer every conceivable configurable property and variation – the focus in effort in developing a set of controls should be on producing a set of controls that behave in a similar fashion across applications (ie the user should not have to ‘learn’ a new set of behaviour to use an application).  It is not generally a good thing from the user’s point of view to allow the programmer to develop their own ‘custom’ approach to GUI design and behaviour.
  4. There should be a clear hierarchy of classes based on the discrete functions/properties that commonly recognised components play.  We have enough history with computer GUIs to now know which components are best used for what purpose (ie. it is not helpful to call everything a Window! – a Button is clearly not the same kind of thing as a Frame)
  5. A suggested hierarchy is:
    1. An Application class – contains all application and event related procedures.
    2. A Window class – this usually ends up being referred to as the main window.  A Window is the region of screen used by the application to interact with the user.  The Window is responsible for management and layout of the user interface in general, more specifically - menubars, toolbars, statusbars and panels – as well as exiting the GUI and shutting down (although this later process is controlled by the application class).  Currently within nx_Controls this class is still referred to as a Frame – this may change in future releases.
    3. A Panel class - the region of a Window where Controls are placed.  A Panel is responsible for the management and layout of the Controls that are placed on it.
    4. A Window may have multiple panels ‘a la the wxNotebook class.  However, this functionality should be a property of the Window class and not conceived of as a separate class or GUI element.  Currently nx_Controls contains a nx_Notebook class – this may change in future releases.
    5. A Control is a GUI element that is used to display information or gain input from the user.  Control classes should be able to be readily combined to allow the programmer flexibility in achieving the GUI functionality required.  Controls should be able to pass default information between themselves.  Controls should implement a permissions concept (ie. some controls are read only some are read/write – this has not been implemented in this release of nx_Controls).

Description of nx_Control classes

All nx_Control classes inherit a virtual class (nx_Control) and the relevant wxWindows class (eg. nx_ListBox inherits wxListBox).  In this way the nx_Controls maintain all the functionality of the wxWindows classes and allow these to be augmented by the virtual class nx_Control.

 

nx_Controls use the two step creation process supported by all wxWindows classes.  This allows for the control to be added or inserted into its parent after its apparent initialisation.  In reality the nx_Control acts as a temporary storage space for the wxWindows control information which is passed to the wxWindow’s Create() method at the point of insertion.  For this reason the only recommended method for creating nx_Controls is through the use of the << operator.

 

The following provides a description of the nx_Controls class set:

Class: nx_Frame

Description:

This class is the usual wxFrame class except that you can insert (ie. <<) menus, panels and notebooks into it.  Note that you cannot insert or add nx_Controls directly into the Frame.  Controls can only be inserted into nx_Panels.

Methods:

Class: nx_Panel

Description:

An nx_Panel managers nx_Controls via nx_Groups (ie. wxSizers).   The Panel is the area into which Controls are inserted.  However, nx_Controls must be inserted using an nx_Group.   Because the adding of controls is wxSizer based the programmer does not need to concern themselves with the layout of the controls as this is all taken carer of by the relevant wxSizer.  nx_Controls just make this process even simplier.

Methods:

Class: nx_Notebook

Description:

This class is the basic wxNotebook with the ability to insert nx_Panels.

Methods:

Class: nx_Group

Description:

The nx_Group class is essentially a single wxSizer.  nx_Group and nx_EndGroup are used in pairs to signify the beginning and ending of each grouping of controls.  Groups are stackable so that it is possible to groups within groups.  In fact this is the preferred way in which to construct the GUI.  Using this approach means that all layout is done via wxSizers.

Methods:

 

Class: nx_Control

Description:

This is an abstract class inherited by all nx_Controls.

Methods:

 

 

Class: nx_Button

Description:

A basic wxButton.  However an event function can be attached to the button using the class constructor.  Furthermore output from the button (always a Boolean of value ‘true’) can be sent to other nx_Controls.

Methods:

 

 

Class: nx_CheckBox

Description:

A standard wxCheckBox but with the option of attaching an event function and ability to pipe output directly to other nx_Controls.  Piped output from CheckBoxes is always a Boolean value good for setting other controls their min or max value.  It sends the text ‘true’ or ‘false’ to TextCtrls.

Methods:

Class: nx_TextCtrl

Description:

A standard wxTextCtrl but with nx_Control functionality.  Piped output can be used to good effect with ListBoxes – ether adding an item to the ListBox or replacing a selected item in the ListBox.  A number (eg. the text ‘10’) can be used to control the value of Sliders or SpinCtrls.  Boolean values (eg. the text ‘true’) can be used to control CheckBoxes.

Methods:

Class: nx_Slider

Description:

A wxSlider – although only horizontal sliders are supported in this release.  The slider comes with autoticks and a StaticText label.  Numeric output can be piped to TextCtrls or SpinCtrls types, if piped to ListBoxes  or ListCtrls the control will select the item whose index corresponds to the value provided by the Slider.

Methods:

Class: nx_SpinCtrl

Description:

A standard wxSpinCtrl but with a label, the option to attach an event function, and the ability to pipe output to other controls.

Methods:

Class: nx_ListBox

Description:

A basic wxListBox but comes with a StaticText label, option to attach a event function through the constructor, and ability to pipe output to other nx_Controls.  Piping output works well with TextCtrls to give an editable List.  Items can be deleted by highlighting and the user pressing the delete key.  This functionality is the default in this release – this may change for future releases.

Methods:

 

Class: nx_ListCtrl

Description:

A Report Type wxListCtrl class.  The ListCtrl class does not make a good target for piped output in this release a ListCtrl needs more information than is generated by the majority of other nx_Control types.  For example, if a TextCtrl sends a wxString value it is not exactly clear what a multicolumn ListCtrl ought to do with it.  If send an integer value (eg, from a slider or SpinCtrl) the ListCtrl will select the item that whose index corresponds to the value sent.  However, output (the selected row and its index) can be sent to other nx_Controls.

Methods:

 

Class: nx_ComboBox

Description:

A standard wxComboBox with the usual nx_Controls added functionality.  The actual items in the ComboBox are inserted after the Combox has been added to a Panel via a Group.  See sample application code for how this works.

Methods:

Class: nx_Menu

Description:

Essentially a wxMenu but with an insertion operator used to insert individual menu items into the menu.  At this point sub-menus are not supported.  This will change in future releases.

Methods:

nx_Menu()

nx_Menu(const wxString& label) – The main constructor.  When used with the nx_Frame’s insertion operator the menu will be inserted into the Frame’s menubar.

nx_Menu& operator<<(nx_MenuItem* obj) – Used to insert menu items into the menu.

 

Class: nx_MenuItem

Description:

Essentially a wxMenuItem.  An event function can be linked to the item using the constructor.

Methods:

nx_MenuItem()

nx_MenuItem(const wxString& title, wxObjectEventFunction func)