Window classes

The basic picture is:

There's a whole slew of classes inheriting from JControl, but graphing them isn't really worth it.

JMother is a misleading name - of course any window may have children.

<JWindow.hpp> defines class JWindow, a couple of exception types, and JWindowPtr. Methods to do with general window tasks are to be found here - repositioning, style, event routing, painting, setting text. Event handling is discussed here.

The JWindowPtr class is used as a virtual constructor for window objects: when given a PM window handle, it will return either the pointer to the existing JWindow object (if the window is already known to JLib), or create a new one. Because a pointer to the original object is returned if possible, you can cast it to its `real' type. The gory details of the windowing system are discussed here.

Methods for traversing and manipulating window hierarchies live here: parent(), setParent(), childWithID(), similarly for owners. Note that the adopt() method is not for setting a window's parent, but for doing event handling.

Window timers live here too, and note the JWindow::cursor class.

<JMother.hpp> defines class JMother, which defines the common behaviour of frames & dialogs. Help id, minimum & maximum sizes, frame furniture( accelerator table, icon, menubar), and the ability to save the position of the window in an ini file.

JMother introduces three handy methods: command(), syscommand(), and closing(). The first two are shortcuts, to avoid having to add a JCmdHandler, giving immediate access to WM_COMMAND & WM_SYSCOMMAND messages sent to the window. The closing method is called when the user tries to close the window. Returning false ends the current message loop (ie. the application).

<JDialog.hpp> defines JDialog. Dialogs can be (and usually are) loaded from resource modules, and may be shown modally. Note the default implementation of closing here doesn't end the message loop.

<JFrame.hpp> defines JFrame. A frame window has a client, and can have frame controls.

<JFrmeCtl.hpp> defines the JFrameCtl interface, which is implemented by three JLib classes. The idea is that any window can be a frame control, but must be wrapped up in one of these first. The JLib classes are:

• JToolbar - <JToolbar.hpp>, really just a bitmap menu. See the Paint sample for an example.
• JStatbar - <JStatbar.hpp>, a static text control at the bottom of the window.
• JDlgbar - <JDlgbar.hpp>, a dialog loaded as a frame control and given a border. To show the sort of thing you can do.

<JMWindow.hpp> defines JMWindow and JObjectWindow. Use these as dummy windows, not for display purposes, but to handle asynchronous notifications. Object windows are still object windows, and should not be created in the main thread (or the same thread as that in which you create normal windows).

<JMenu.hpp> defines JMenu. There's just the one class for popup menus, menubars, and any other kind of menu you might want. Support for `default entry' attribute setting, and popup.

To load a menu which you want to use as a popup context menu, use the basic constructor which takes a JResID and leave the default value of JWindow::theObjectWindow as the owner.

<JControl.hpp> defines JControl. You rarely need to worry about this class; when adding new control classes to JLib you must derive from here (or from a class deriving from here, of course). A couple of style constants are found inline. The normal way of setting up controls in dialogs is something like:

class MyDialog : public JDialog
{
   JEntryField ef;

 public:
   MyDialog( JFrame *owner) : JDialog( owner, JResID( did_mydialog)),
                              ef( this, did_txtentry)
   {}
};

Sometimes you need to subclass a library control in order to get at its notification events -- see event handling.

Controls in JLib are of two sorts: native PM controls & custom controls. The native ones are just that, wrappers around WC_whatever window classes; the custom controls are new. Just for reference here, the new controls are:

• JCanvas
• JViewer
• JSplitWindow

Static controls generate no notification codes; they are things like labels, groupboxes, and borders:

JStaticText	<JStaticT.hpp>	Simple text labels
JStaticBitmap JStaticIcon	<JStaticG.hpp>	Icon & bitmap labels
JGroupBox	<JGrpBox.hpp>	Group box with header
JBorder	<JBorder.hpp>	A border; can be made to bevel in or out.
JWrapText	<JWrap.hpp>	Very similar to JStaticText but can tell you how tall it needs to be to display all the text.

Push buttons, graphic buttons, radio-buttons & checkboxes. Class JButton is defined in <JButton.hpp>, which provides the common interface to types of button which use WC_BUTTON. The actual classes you can instantiate are:

JPushButton	<JPushBut.hpp>	Normal push buttons; most dialogs should have at least three...
JRadioButton JCheckbox	<JSelButt.hpp>	Checkboxes and radio-buttons.
JCustomButton	<JCusButt.hpp>	Custom buttons: you draw the button graphic. Note this is an abstract class.
JGButton	<JGButton.hpp>	Wrapper of the WC_GRAPHICBUTTON window class; toggles, animations, buttons with pictures on in general.

<JEntFld.hpp> defines class JEntryField. It's an entryfield; note that the default maxiumum length is whatever PM gives you, which tends to be 32. This is often unhelpful!

<JMLE.hpp> defines class JMLE, which is a multi-line edit control. MLEs are evil controls, and rarely work quite as you desire.

<JListbox.hpp> defines class JListbox, which is a normal PM listbox. There are nested item and cursor classes for examining contents and selections. This type of listbox can only contain text.

<JCstLbox.hpp> defines class JCustomLBox, which allows you to draw the listbox items. This class is abstract.

<JCBox.hpp> defines class JComboBox. This class inherits from JListbox, and has a entryfield() method to get hold of a JEntryField for the combobox's entryfield part.

Not put with buttons 'cos they're not, really.

<JSpinBut.hpp> defines JSpinButton, JNumericSpinButton, and JTextSpinButton. The latter two classes inherit from the first; they have different methods due to the different type of data they're designed to hold.

<JNotebk.hpp> defines JNotebook, which is a notebook control. There's a JPage class too, which is used to talk about the pages of a notebook. See the header file for an example of what owner/parent combinations are needed to load dialogs for pages.

The notebook control knows about warp 4, and will convert a warp3 style notebook if appropriate. This means you should define your notebooks in the resource file without the warp 4 style, and let JLib convert it for you at runtime, if appropriate.

<JSlider.hpp> defines JBSlider, which you can wrap around existing controls but cannot use to create sliders; JVertSlider, JHorzSlider, and JProgressBar, which you can.

Owner draw isn't explicitly supported, but if you set the ownerdraw style, and attach a JOwnerDrawHandler somewhere sensible, you ought to be okay.

<JVSet.hpp> defines JValueset, which is a value set control. This is generally used as a kind of palette. If you need it, you'll know it.

<JScrlBar.hpp> defines JScrollbar, which is a scrollbar. You shouldn't need to use this class directly: to get a scrolling client area, use JViewer, and use some form of slider for that purpose.

Containers are by far the most interesting, featureful PM control, and JLib provides a fairly high-level interface to them.

<JCnr.hpp> defines the JContainer control class, along with a bunch of smaller classes for doing sorting, filtering, and iterating. Lots of methods here; support for settings context menus & turning off drags. If you want to allow drops on the container background and so on, you'll need to derive off your own class & override methods.

<JCnr2.hpp> defines JCnr, which is a namespace for the various constants and so forth which the container control uses.

<JCnrRec.hpp> defines JCnrRecord, the base class for records which live in containers. Note the bizarre allocation syntax: you should create objects with new and supply the container for which the record is destined using placement syntax:

JContainer *myCnr;

JCnrRecord *rec = new( myCnr) JCnrRecord( strName, hIcon);

You'll usually need to derive a class from JCnrRecord to get access to its event handling methods and add additional data.

<JCnrCol.hpp> defines JCnrColumn. If you want a container in details view, you must first insert columns. Use new to create instances, but you don't need placement syntax.

<JCnrODH.hpp> defines a bunch of handler & event classes for containers. There's one handler for just drawing a custom background, and another handler for drawing records, column cells, container titles and so on. To make a container use the handlers, you'll need to call its setCustom... method.

<JViewer.hpp> defines JViewer. This is a viewport class: given a client window, it provides scrollbars & support for keyboard use to scroll around it. A typical situation is to have one of these as the client of a frame window, and the window you want to display as the viewee of the viewer. The viewer takes its maximum size from the size of the viewee you give it on construction; to alter this, use the setVieweeSize() method.

<JCanvas.hpp> defines JCanvas and JBufferedCanvas. If you want a window to draw into, use this. The second class allows you to draw to an off-screen buffer, and copy up to the screen in one go, decreasing flicker.

Note that JCanvas is abstract; you need to supply a paint() method.

<JSplit.hpp> defines JSplitWindow. This control has two client windows which share its area, and gui support for altering the proportion given to each.