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
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.
- 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).
- 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.
- 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.
- 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)
- A
suggested hierarchy is:
- An
Application class – contains all application and event related
procedures.
- 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.
- 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.
- 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.
- 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).
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:
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.
- nx_Frame() -
default constructor
- nx_Frame(const
wxString & Title) – use this constructor to
actually create your frame. It also
sets up the menubar ready for menus to be
inserted.
- nx_Frame& operator<<(nx_Panel* obj) – Inserts an nx_Panel
into the frame. Calls the nx_Panel’s Construct method.
- nx_Frame& operator<<(nx_Notebook* obj) – Inserts an nx_Notebook
into the frame and calls the nx_Notebook’s Construct
method.
- nx_Frame& operator<<(nx_Menu* obj) – Inserts an nx_Menu
into the Frame’s menu bar.
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.
- nx_Panel()
– the default constructor.
- nx_Panel(wxOrientation orientation = wxVERTICAL,
const wxString & title =
"Untitled" ) – The main constructor. This title parameter is mainly used when
inserting a panel into a notebook (the title is the tab title for the
page).
- nx_Panel& operator<<(nx_Group* obj) – Inserts an nx_Group
into the nx_Panel. This in effect adds a wxSizer to the Panel.
Nx_Panels need at least one nx_Group to be inserted for the nx_Controls
for that panel to belong to.
- nx_Panel& operator<<(nx_EndGroup obj) – nx_Groups
are stackable in that nx_Groups can have sub nx_Groups. The
nx_EndGroup signifies the end of a group.
- nx_Panel& operator<<(nx_Control* obj) – nx_Controls
may be inserted into the panel.
However, there needs to be at least one nx_Group
already inserted for the controls to be managed correctly.
This class is the basic wxNotebook
with the ability to insert nx_Panels.
- nx_Notebook() – The default constructor
- void Construct(wxWindow*) – Not
intended to be called directly. This method Constructs
(ie. Creates()) the
Notebook. This method is called by
the parent Frame when inserting the nx_Notebook.
- nx_Notebook& operator<<(nx_Panel* obj) – Used to insert a nx_Panel
into a nx_Notebook. Inserting a nx_Panel is the same as adding a page to the wxNotebook.
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.
- nx_Group(wxOrientation orient = wxVERTICAL)
– Constructor for adding a group that is not framed and has not title.
- nx_Group(const
wxString& label, wxOrientation
orient = wxVERTICAL) – constructor a group that
is framed and has a title.
- nx_Group& operator<<(nx_Control* obj) – Used for inserting nx_Controls into this group. The controls in the group will be
managed by the wxSizer associated with the
group.
This is an abstract class inherited by all nx_Controls.
- virtual void Construct(wxWindow*
parent) - This is called by the (parent) object that this object is being
added to. This method is usually
called by the insertion operator of the parent. This method in turn calls the wxWindows Create()
method. It is important to realise
that the wxWindows portion of the nx_Control does not exist until it is inserted into
the parent.
- void PipeOutputTo(nx_Control* target_ctrl) –
This method sets up the pipe of output from this nx_Control
to the target nx_Control. The type of output (ie.
numeric or text) will depend on the type of control. The way in which the output is
interpreted will be depend on the receiving control. For example an nx_Slider
control will send numeric output.
If send to an nx_ListBox the slider
output will be used to select the entry from the list using the slider
output as the index. Another
example - a ListBox sending output to a textctrl will mean that the textctrl
content is set to that of the selected ListBox
item.
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.
- nx_Button()
– Default constructor. Does not
Create() the wxWindows object – this only occurs
when this nx_Control is inserted into the parent
Panel via a Group.
- nx_Button(const
wxString& label, wxObjectEventFunction
func = 0, wxEventType
event = wxEVT_COMMAND_BUTTON_CLICKED) – Usual
constructor with the option to attached an event function to the
Button. Does not Create()
the wxWindows object – this only occurs when
this nx_Control is inserted into the parent
Panel via a Group.
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.
- nx_CheckBox()
– The default constructor. Does not
Create() the wxWindows
object – this only occurs when this nx_Control
is inserted into the parent Panel via a Group.
- nx_CheckBox(const
wxString& label, wxObjectEventFunction
func = 0, wxEventType evt = wxEVT_COMMAND_CHECKBOX_CLICKED)
– The usual constructor with the option to attach an event function to the
CheckBox. Does not Create()
the wxWindows object – this only occurs when
this nx_Control is inserted into the parent
Panel via a Group.
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.
- nx_TextCtrl()
– The default constructor. Does not
Create() the wxWindows
object – this only occurs when this nx_Control
is inserted into the parent Panel via a Group.
- nx_TextCtrl(const
wxString& label, wxObjectEventFunction
func = 0, wxEventType evt = wxEVT_COMMAND_TEXT_ENTER)
– The usual constructor with the option to attach an event function. Does not Create()
the wxWindows object – this only occurs when
this nx_Control is inserted into the parent
Panel via a Group.
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.
- nx_Slider()
- The default constructor. Does not
Create() the wxWindows
object – this only occurs when this nx_Control
is inserted into the parent Panel via a Group.
- nx_Slider(const
wxString& label, wxObjectEventFunction
func = 0, wxEventType evt = wxEVT_SCROLL_ENDSCROLL)
– The usual constructor with the option to attach an event function. Note that the default EventType is wxEVT_SCROLL_ENDSCROLL
– this may need to be changed to wxEVT_SCROLLfor
some situations. Does not Create() the wxWindows object
– this only occurs when this nx_Control is
inserted into the parent Panel via a Group.
A standard wxSpinCtrl
but with a label, the option to attach an event function, and the ability to
pipe output to other controls.
- nx_SpinCtrl()
- The default constructor. Does not
Create() the wxWindows
object – this only occurs when this nx_Control
is inserted into the parent Panel via a Group.
- nx_SpinCtrl(const
wxString& label, wxObjectEventFunction
func = 0, wxEventType evt = wxEVT_COMMAND_TEXT_ENTER)
– The usual constructor with the option to attach an event function. Note that the default EventType is wxEVT_COMMAND_TEXT_ENTER
– this may need to be changed for some situations (ie.
if you want to hear about every change in value). Does not Create()
the wxWindows object – this only occurs when
this nx_Control is inserted into the parent
Panel via a Group.
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.
- nx_ListBox()-
The default constructor. Does not Create() the wxWindows object
– this only occurs when this nx_Control is inserted
into the parent Panel via a Group.
- nx_ListBox(const
wxString& label , wxObjectEventFunction
func = 0, wxEventType evt = wxEVT_COMMAND_LISTBOX_DOUBLECLICKED)
- The usual constructor with the option to attach an event function. Does not Create()
the wxWindows object – this only occurs when
this nx_Control is inserted into the parent
Panel via a Group.
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.
- nx_ListCtrl()
– Default constructor – . Does not Create() the wxWindows object
– this only occurs when this nx_Control is
inserted into the parent Panel via a Group.
- nx_ListCtrl(const
wxString& label, wxObjectEventFunction
func = 0); - The usual constructor – The ListCtrl will have a StaticText
object attached and optionally an event function. Does not Create()
the wxWindows object – this only occurs when
this nx_Control is inserted into the parent
Panel via a Group.
- long GetFirstSelected() –
Returns the first selected item.
- nx_ListCtrl& operator<<(const
wxString& col) – The
insertion operator for ListCtrls – it inserts
columns into the ListCtrl. This must be done after the ListCtrl has been added to
a panel via a group. See sample
application for how this works.
- const
wxString & GetItem(int index, int col) - Retrieves the item text at zero-based index,
and zero-based column
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.
- nx_ComboBox()
– The default constructor – . Does
not Create() the wxWindows
object – this only occurs when this nx_Control
is inserted into the parent Panel via a Group.
- nx_ComboBox(const
wxString& label, wxObjectEventFunction
func = 0, wxEventType evt = wxEVT_COMMAND_COMBOBOX_SELECTED) - The usual constructor with the option
to attach and event function to the ComboBox. Does not Create()
the wxWindows object – this only occurs when
this nx_Control is inserted into the parent
Panel via a Group.
- nx_ComboBox& operator<<(const
wxString& item) – Insertion operator for ComboBox – this is used to insert the actual values in
the combox box.
This must be done after
the control is inserted into a Panel via a Group.
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.
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.
Essentially a wxMenuItem. An event function can be linked to the item
using the constructor.
nx_MenuItem()
nx_MenuItem(const wxString& title, wxObjectEventFunction func)