X11PaneDispatcher

X11PaneDispatcher Class

X11PaneDispatcher objects manage events from the system’s display, control posititioning and rendering of subpanes within the main pane, and help communicate events between the main window’s pane and the subwindows’ panes.

The positioning of subwindows within the parent window is controlled by the arguments to the attachTo methods; in particular, these methods accept a geometry specification, as an argument, which has the following format.

width[%]xheight[%][+x[%]+y[%]]

If a dimension does not contain a percent (‘%’) sign, the dimensions are in pixels. With a percent sign, the dimensions are a fractional percentage of the parent pane’s width or height.

Also, for some Pane classes, like dialog windows, if the geometry does not include the x and y dimensions, then the class positions the window centered over its parent window.

The X11PaneDispatcher method new creates a X window, although the window of the X11PaneDispatcher itself is not normally visible, the window is provided for subclass panes whose windows will appear within the main X11Pane window.

Subclasses can reimplement default methods like new and the event handler methods if necessary. It is also possible for subclasses to implement event handlers with other method messages than those given here. The X11PaneDispatcher object can use these subclasses’ methods if they are available.

Subclasses, however, should use the setMethodHandler method, described below, to register these callback methods.

Handler Classes

The following event handlers and the default names of the callback method that handles the event, are available to X11PaneDispatcher objects and its subclasses. Handler methods need to take as arguments a reference to a subpane object, and the InputEvent object from the system. See X11TerminalStream.

Handler Class  Event Class    Description                     Default Handler Method
"resize"       RESIZENOTIFY   Called when the user            subPaneResize
                              resizes a window.

"move"         MOVENOTIFY     Called when a user              subPaneMove
                              moves a window.  
                              Depending on the 
                              window manager, an
                              application might also
                              need to make sure the
                              window is resized 
                              correctly.

"expose"       EXPOSE         Called whenever the display     subPaneExpose
                              server generates exposes a 
                              window due when raised, 
                              uncovered, resized, or other
                              change.

"kbdinput"     KEYPRESS       Called when the user presses    subPaneKbdInput
               KEYRELEASE     a key and the application's
                              window has the focus.

"pointerinput" BUTTONPRESS    Called when a mouse button      subPanePointerInput
               BUTTONRELEASE  is pressed or released.

"pointermotion" MOTIONNOTIFY  Called whe the pointer is       subPanePointerMotion
                              moved.

"selectionrequest"
             SELECTIONREQUEST Received when another program   subPaneSelectionRequest
                              requests the X selection.
                              This callback is here mainly
                              for completeness; presently, X
                              selection events are handled
                              internally, and only with the
                              library functions used by
                              X11TextEditorPane objects.

"selectionclear"        
               SELECTIONCLEAR Received when another program
                              requests the X selection. Currently,
                              on library functions used by
                              X11TextEditorPane objects use this
                              internally but applications can use this
                              event to update their status if
                              necessary.
"wmfocuschange" WMFOCUSCHANGENOTIFY
                              Received from the window manager when the
                              pointer enters or leaves a window, or when
                              the window manager raises a window.  The
                              xEventData1 instance variable contains the
                              type of X event, either FocusIn or FocusOut.

"enternotify" ENTERWINDOWNOTIFY
                              Received when the pointer enters a
                              window from another window.

"leavenotify" LEAVEWINDOWNOTIFY
                              Received when the pointer leaves a
                              window.

"focusin"     FOCUSIN         Received when the application signals
"focusout"    FOCUSOUT        a change of widget focus; for example,
                              when the user presses the Tab
                              key.

"map"         MAPNOTIFY       Received when the pane's window is
                              mapped onto the display.

"destroy"     WINDELETE      Called when the user closes the
                              application window.

Handler Methods

A handler typically takes as its arguments a reference to a subpane, and the event. Although the subpane reference parameter can be declared as an Object, it is in actual use a Symbol object, with the reference defined by the attachTo method. The handler should be able to pass the event along to any subpanes of the receiver pane if necessary, by checking whether subpanes implement their own handlers. Here, for example, is the X11PaneDispatcher class’s subPaneResize method.

X11PaneDispatcher instanceMethod subPaneResize (Object __subPane, 
					      InputEvent __event) {
  "Dispatch an Resize event to the subpanes of the
   receiver pane."
  X11Pane new containerPane;
  self size x = __event xEventData3;
  self size y = __event xEventData4;
  containerPane = *self container;
  XResizeWindow (containerPane xDisplay, containerPane xWindowID,
		 self size x, self size y);
  if (__subPane isInstanceMethod "subPaneResize") {
    __subPane methodObjectMessage __subPane handleResize, __subPane,
      __event;
  }
  return NULL;
}

The internals of the subpane API are likely to change and be expanded in future releases. Using the methods described here and in other sections should help insure that applications are compatible with future Ctalk releases.

Instance Variables

canFocus

A Boolean that determines whether the widget is highlighed when the pointer passes over it, or the application sets the focus; for example, by pressing the Tab key.

If this variable is true, which is the default, then the class should also declare event handlers for focus in and focus out events. Otherwise, the program prints a warning each time the shiftFocus method, described below, calls a NULL Method object.

handleDestroy

A Method that provides the default handler to delete a subpane window and its data.

handleEnterNotify

handleLeaveNotify

Handlers for events that are generated when a pointer crosses from one window to another.

handleFocusIn

handleFocusOut

Handles highlighting or un-highlighting a widget when receiving a FOCUSIN or FOCUSOUT event from the application; for example, when the user presses the Tab key.

handleKbdInput

A Method that provides the default handler for subpanes to handle keyboard input.

handleMap

Called when the program recieves a MAPNOTIFY event for the pane’s window.

handleMove

A Method that provides the default handler for moving subpane windows.

handlePointerInput

A Method that provides the default handler for pointer input (mainly ButtonPress) events.

handlePointerMotion

A Method that provides the default handler for pointer motion events.

handleResize

A Method that provides the default handler for resizing subpane windows within the main window.

handleSelectionClear

A Method that provides the default handler for SelectionClear events.

handleSelectionRequest

A Method that provides the default handler for SelectionRequest events. Currently, this callback is here for completeness; X selection events are handled internally, and only in the library functions used by X11TextEditorPane objects.

handleWMFocusChange

The method that handles the events received from the desktop’s window manager when it changes the window focus in response to a pointer motion or click; or when the window manager raises a window.

hasFocus

An Integer that is true if the current subpane has the input focus. For programs with only a single widget class, this variable is not used.

highlight

A Boolean that indicates whether the widget is displayed highlighted.

modalWin

When a dialog window is popped up over the main window, this holds the window ID of the popup. The handleSubPaneEvent method uses this to determine how the application’s main window should respond to X events; generally it keeps the dialog window above the main window until the dialog window is withdrawn. When their is no window popped up over the main window, the value of modalWin is zero (‘0’).

tabFocus

A Boolean that determines, if true (which is the default), whether the handleSubPaneEvent method intercepts the Tab key in order to shift the input focus when it is pressed. If tabFocus is true, the subpane’s class must implement methods to handle the focusin and focusout events that shifting focus with the keyboard implements, or the program will display warning messages when it can’t find the methods.

Instance Methods

attachTo (Object parentPane)

attachTo (Object parentPane, String geometry)

Attach the receiver to its parent pane, typically a X11Pane or X11PaneDispatcher. Also creates a X window, although X11PaneDispatcher windows themselves are not normally visible.

When the subwindow is attached to the parent window, the Ctalk library creates the pane object’s window and graphics context, and clears the window to the background color of the pane object’s backgroundColor instance variable; for example, with an expression like this:

myCanvasPane backgroundColor = "blue";

Otherwise, the method clears the subpane’s window to black.

The geometry argument, if present, defines the size and placement of the subpane’s window within the parent window. A geometry specification has the form:

width[%]xheight[%]+x[%]+y[%]

The dimensions are in pixels, unless a percent sign (‘%’) follows a dimension. In that case, the dimension is a fractional percentage of the parent pane’s width or height. The String may contain a combination of absolute and relative dimensions.

handleSubPaneEvent (InputEvent event)

Handle an input event from the window system. Typically the parent pane’s inputStream provides the event. See X11TerminalStream.

This method also checks keypresses for the Tab key, and calls the shiftFocus method in order to shift focus between a window’s subpanes when the user presses Tab.

new (dispatcherName)

Create a new X11PaneDispatcher object. Initializes the instance variables to the default subpane event handlers and the container mode to ‘full’. If the argument list contains more than one label, created new X11PaneDispatcher objects with the names of each label.

setMethodHandler (String handlerType, Method handlerMethod)

Set the pane’s handler for handlerType to handlerMethod. Currently supported handler types are: ‘resize’.

shiftFocus (void)

When the user presses Tab, handleSubPaneEvent calls this method, which highlights a window’s subpanes in succession, if the subpanes can take the input focus.

Refer to the canFocus instance variable, and the handlers for focus in and focus out events. These event handlers are called by the program, and are not the same as the handleWMFocusChange handler, which is called when the window focus changes on the desktop.

clearFocus (void

Called before shifting the focus highlight to a new pane to insure that only one pane indicates that it should receive focus, including the synthetic focus that is assigned when shifting focus using the Tab key.

subPaneDestroy (Object subPaneRef, InputEvent destroyEvent)

The default handler for WINDELETE events. Like the other method handlers, subPaneRef is typically a Symbol object. The X11TerminalStream section describes these events. See X11TerminalStream.

subPaneGeometry

A String that stores a subpane’s geometry specification, if any. For an explanation of geometry string’s format, refer to the attachTo method, below.

subPaneKbdInput (Object subPaneRef, InputEvent kbdInputEvent)

The default handler for KEYPRESS and KEYRELEASE events. Like the other method handlers, subPaneRef is typically a Symbol object. The X11TerminalStream section describes these events. See X11TerminalStream.

subPaneMove (Object subPaneRef, InputEvent moveNotifyEvent)

The default event handler for MOVENOTIFY events from the system’s GUI. Like the other method handlers, subPaneRef is typically a Symbol object. The X11TerminalStream section describes these events. See X11TerminalStream.

With some window managers, a subPaneMove method might also need to handle RESIZENOTIFY events.

subPanePointerMotion (Object subPaneRef, InputEvent event)

subPanePointerInput (Object subPaneRef, InputEvent event)

The default handlers for MOTIONNOTIFY, and BUTTONPRESS and BUTTONRELEASE events. Like the other method handlers, subPaneRef is typically a Symbol object. The X11TerminalStream section describes these events. See X11TerminalStream.

subPaneResize (Object subPaneRef, InputEvent resizeNotifyEvent)

The default resize handler for subpane windows. Typically subPaneRef is a Symbol object that contains a reference to the subpane object. The resizeEvent argument is typically a RESIZENOTIFY event from the system’s GUI. See X11TerminalStream.