ToC DocOverview CGDoc RelNotes FAQ Index PermutedIndex
Allegro CL version 11.0

Common Graphics operators


3d-border-width

Generic Function, cg package

Arguments: widget

Returns the 3d border width of widget.


3d-style

Generic Function, cg package

Arguments: group-box

Returns or sets (with setf) the 3d style width of group-box. See the description of the group-box control.


a-visual-style-is-active

Function, cg package

Arguments:

Returns true if a Microsoft "Visual Style" is currently in effect; returns nil otherwise. The value will always be nil on platforms other than Microsoft Windows.

A Visual Style is in effect on Windows if there is a "manifest file" and the user has not selected "Windows Classic" in Control Panel | Display | Themes. See ide:include-manifest-file-for-visual-styles for more information.


about-to-show-menu

Generic Function, cg package

Arguments: window menu

Called whenever a menu is about to be made visible. window is the owning window. menu is the menu about to be displayed.

The default method calls about-to-show-menu recursively on the selected child of window. An application may add methods to this generic function in order to modify a menu that is about to be shown, making it suitable for the current context. This is most useful for pull-down menus, since they are not invoked by application code that could otherwise modify the menu before invoking it. You might, for example, want to make certain menu-items unavailable when the menu is displayed because the items are not meaningful in the current environment. The menu command Cut should typically be unavailable when nothing is selected, for example.

See cg-events.htm for information about event handling in Common Graphics. See also the menu chapter in the IDE User Guide, which has examples using this function.


above-parent

Generic Function, cg package

Arguments: outline-item

Returns whether an outline-item will be drawn above its parent item rather than in the normal location below the parent. The value may be set at creation time by passing the above-parent initarg, or any time later by calling (setf above-parent). The default value is nil.

Placing some outline-items above their parent and others below could be used to distinguish the two groups of items in some application-specific way.

An outline-item will be placed above its parent item only when its above-parent property is true and the outline widget's handle-above-parent property is also true.


active

Generic Function, cg package

Arguments: timer

A boolean value indicating whether a timer is currently running. An active timer fires each time its interval passes, while an inactive timer does nothing. This property of a timer will be true if start-timer has been called on the timer more recently than stop-timer has. If the active property is explicitly modified by an application from nil to true, then start-timer is called internally, and if the active property is explicitly modified from true to nil, then stop-timer is called internally. Therefore, in order to wrap all starting and stopping of timers, it is sufficient to add start-timer and stop-timer methods.

active is a property of the timer class.

See cg-timers.html for more information on timers.


add-application-window

Generic Function, cg package

Arguments: window &optional (key (name window)) (subkey (default-application-window-subkey)) always

Caches a window so that it can later be retrieved by find-application-window using the specified key (which defaults to the name of the window being cached)) and the specified subkey (which defaults to the value returned by default-application-window-subkey).

Typically you would accept the default values for key and subkey, and later pass only the name of the window to find-application-window. But these arguments could be any two values at all, as long as you pass values that are eq to them to find-application-window to find this window.

If always is true, then the specified window will replace any existing window that has the same key and subkey in the cache of all application windows. If always is nil, then the specified window is not added to the cache of all application windows if there is already a window there that has the same key and subkey. The default is nil.

See also remove-application-window.


add-child-outline-item

Generic Function, cg package

Arguments: outline &key value

Creates an outline-item that has the specified value, and adds it to the specified outline as a child of the currently selected item, if any, and otherwise as a top-level item. The item will be positioned at the top of its siblings.

This function is a specialization of the more general function add-outline-item-value, and could be used directly for an interactive command to create a child of the selected item.


add-class-grid-row

Function, cg package

Arguments: class-grid data-object &key *index scroll-into-view focus-on-row

Adds a single object to the list of objects that a class-grid is displaying. An alternative is to replace the whole set of displayed objects by calling (setf value) on the grid, passing a list of all objects to display.

Internally this creates a class-grid-body-row and adds it to the body row-section of the grid-widget.

class-grid is the class-grid to which an object will be added.

data-object is the new object to display. It should be an instance of the edited-class of the class-grid.

index specifies the position of the new grid-row among the existing rows. It may be either an integer index, where zero means to add the row at the very top, or else nil to add the row at the very bottom. The default is nil.

If scroll-into-view is true, then the body row-section will be scrolled as needed to make the new row fully visible. If nil, then this is not done. The default is nil.

If focus-on-row is true, then the keyboard focus within the grid will be moved to a cell of the new row. If nil, then this is not done. The default is nil. A true value still does not move the keyboard focus to the class-grid itself, but when it is next moved there the focus will be in the new row. An application could call set-focus-component to move the focus to the class-grid to allow the user to immediately edit the new row.

Modifying the list of instances that a class-grid displays will call the grid's on-change function because the list of instances is stored as the value property of the widget.

See also delete-class-grid-row.


add-column

Generic Function, cg package

Arguments: list-view-or-grid-column-section list-view-column-or-grid-column &optional index

For a list-view control, adds a new list-view-column specified by list-view-column-or-grid-column to list-view-or-grid-column-section at index. An index of zero indicates the leftmost position, 1 means second from the left, and so on. An index of -1 (this is the default for list-views) means in the rightmost position. See the description of the list-view control.

For a grid-widget control, adds a grid-column, specified by the list-view-column-or-grid-column to the grid-column-section specified by list-view-or-grid-column-section at the specified index among the columns of that section. An index of zero indicates the first (leftmost) position. A huge number can be used for index to add to the end. The default index for the grid-widget method is zero. Alternately, (setf subsections) can be called to replace the entire set of columns of the column section.


add-common-status-bar

Generic Function, cg package

Arguments: window &rest options &key (font (status-bar-font window)) parts min-height (minimum-height min-height) size-grip-p along-top-p name

Creates a status-bar that has multiple sections, rather than allowing multiple lines of text as with status-bars created by add-status-bar. The status bar is placed along the bottom of window. Panes that are siblings of the new status-bar and overlap with it are automatically resized so they no longer overlap with the new status-bar. The status bar added by this function has a more Windows look and feel compared to that added by add-status-bar but, as mentioned, supports only one line of text.

The arguments are:

Note that the argument list of this function as returned by arglist (or describe or other tools) includes &rest options. This is included for internal technical reasons. From the programmer's point of view, there is one required argument and a number of keyword arguments.


add-component

Generic Function, cg package

Arguments: widget dialog &optional behind hidden

Adds the control specified by the widget argument to the dialog-window dialog.

The keyword arguments are:

widget is returned.


add-component-to-tab

Generic Function, cg package

Arguments: tab-control tab-id widget

Adds widget to tab-control on the tab whose programmatic name (id) is tab-id. (A tab on a tab-control is an instance of a tab-info object. Applying name to a tab-info results in a suitable value for the tab-id argument.) Note that the control specified by widget is not moved so that it is over the tab-control, but it will be exposed when the tab it is on is selected and hidden when another tab is selected.

See the description of the tab-control class/control.


add-global-keyboard-accelerator

Function, cg package

Arguments: event-synonym function-name

This function establishes a global keyboard shortcut that does not have a corresponding menu-item on a top-level menubar.

event-synonym should be a character or a list of modifier keys and a character, to denote a keyboard event that should run some function globally. This argument can be a key-chord that will invoke the command. An event-synonym always contains a single main non-shift key, plus an optional set of one or more shift keys.

If no shift keys are used, then the event-synonym consists entirely of a character name like #\A or a key name like vk-comma or vk-f3.

If shift keys are used, then the event-synonym is a list whose members are the names of the shift keys (in any order) and the main non-SHIFT key as the last member. The available shift key names are control-key, alt-key, and shift-key, and they may be used in any combination.

Normally, typable characters (such as letters and numbers) are used only in combination with either control-key or alt-key (or both), since otherwise you could not input the characters as text.

function-name denotes the function to run. The function should take one argument, which will be the top-level window of the window that had the keyboard focus when the specified keys were pressed. The function should return true to disable any further processing of this event, or nil to allow the keyboard event to still be looked up in the top-level window's menu bar or to be otherwise handled by the selected window's event handler.

A global keyboard accelerator will take precedence over any other handling of its keypress event in any window, including windows that have comtabs. (In the IDE, the editor and Debug Window have comtabs. See comtab.)

The function for a global keyboard accelerator will run in the thread that created the window that had the keyboard focus when the keypress event occurred. For standard IDE windows, this will be the IDE GUI thread. If it is desirable to run the code in a Listener thread instead, where user evaluations are normally done, the function eval-in-listener-thread could be used in the accelerator's function to do so.

Global keyboard accelerators can be removed with remove-global-keyboard-accelerator.

Examples

Here are two examples that define global accelerators that move the selected window by 8 pixels either up or down. The first example (to move the window up) illustrates calling a separately defined function and using one of the vk-foo names for keys that don't have printable characters on them, and the second example (to move the window down) illustrates using an in-place function object and using the character that's printed on the lower (unshifted) part of the key.

;; Define a function to move a window upward by eight pixels.
(defun move-up (window)
  (with-positions (pos1)
    (move-window-relative window (nmake-position pos1 0 -8)))
  t)

;; Make alt-backspace move the current window up.
(add-global-keyboard-accelerator
 '(alt-key vk-backspace) 'move-up)

;; Define a lambda function to move a window downward by eight pixels
;; and make control-shift-8 invoke it.
(add-global-keyboard-accelerator
 '(control-key shift-key #\8)
 #'(lambda (window)
     (with-positions (pos1)
       (move-window-relative window (nmake-position pos1 0 8)))
     t)) 
     ;; Return true to override any other control-shift-8 handling

add-header

Generic Function, cg package

Arguments: header-control header-id label &key (index -1) justification width

Adds a new header to header-control, with programmatic name header-id and displaying label. The text in the header is justified according to the justification of the header-control (the value returned by default-header-justification applied to header-control) unless a value for justification is specified. Possible values are :left, :right, or :center. The width is the default width of the header-control (returned by default-header-width applied to header-control) unless a value for width is specified.

index is a fixnum indicating the position of the new header among the other headers on the header-control. A non-negative number indicates a position from the left side, where zero is the leftmost header, and a negative number indicates a position from the right side, where -1 is the rightmost header.

See the description of the header-control class/control.


add-hotspot

Generic Function, cg package

Arguments: window hotspot

Adds hotspot, which must be an existing hotspot object, to a window.

See the description of the hotspot class.


add-item

Generic Function, cg package

Arguments: list-view list-view-item &optional (index -1)

Adds the new item, list-view-item, to list-view at index. An index of zero indicates the topmost position, 1 means second from the top, and so on. An index of -1 (this is the default) means the bottom-most position.

See the description of the list-view control.


add-outline-item

Generic Function, cg package

Arguments: outline new-item parent-item-or-value &key no-redisplay position no-error-p

Adds the outline-item new-item to outline either as a top-level item or as a subitem of the item whose value is parent-item-or-value, at position among its siblings. new-item must be an instance of the outline-item class. outline must be an instance of the outline class.

parent-item-or-value may be either the parent outline-item under which to add the new item, or the parent item's value, or else nil to add the new item as a top-level item. Specifying the parent item by its value is typically convenient, but is less efficient since the item must first be looked up from its value. And if multiple items have this same value, then the wrong parent may be found unless the actual parent outline-item is specified. (If parent-item-or-value is non-nil and no outline-item can be found in outline that matches the specified value, then an error is signaled if no-error-p is nil, and nothing is done if no-error-p is true.)

This function searches only through the currently visible outline-items for parent-item-or-value. If parent-item-or-value specifies an item that is currently hidden (due to an ancestor item being closed), then an error is signaled unless no-error-p is true. As an alternative, (setf range) works regardless of whether the parent item is currently visible.

The value of position should be a non-negative integer, :end or nil. 0 means above all siblings. :end means below all siblings. nil means position according to the on-sort-predicate (if on-sort-predicate is nil or the function true (which always returns true) new-item is positioned at the top among its siblings.)

If no-redisplay is true, the outline will not be redisplayed by this function to reflect the change. You may wish to delay redisplay when there is more than one modification until all modifications are made.

If no-error-p is true, no error will be signaled if the requested action cannot be performed for any reason. Instead, nothing will be done. (Specifying this argument true does not protect against malformed calls to this function, such as specifying a value for new-item which is not an instance of outline-item.)

To change the whole set of child outline-items of a parent outline-item (or all of the top-level items of an outline control), an alternative is to call (setf range) on the parent outline-item or the outline control, passing a list of outline-items as the new value.

If no item was successfully added, then nil is returned. Otherwise two values are returned: (1) the outline-item that was added, and (2) the index of the new item within all currently visible items. (The index will be nil if the new item is not visible because the parent item is closed.)


add-outline-item-value

Generic Function, cg package

Arguments: outline item-value parent-item-or-value &key kind (state :closed) range no-redisplay position no-error-p

Creates a new outline-item instance whose value is item-value, and adds the new item to outline as a child item of the item specified by parent-item-or-value. (If parent-item-or-value is non-nil and no outline-item can be found in outline that matches the specified value, then an error is signaled if no-error-p is nil, and nothing is done if no-error-p is true.)

This function searches only through the currently visible outline-items for parent-item-or-value. If parent-item-or-value specifies an item that is currently hidden (due to an ancestor item being closed), then an error is signaled unless no-error-p is true. As an alternative, (setf range) works regardless of whether the parent item is currently visible.

outline is the outline widget to which the new item is being added.

item-value is an arbitrary value for the new outline-item. See also add-outline-item, which takes an outline-item object instead.

parent-item-or-value may be either the parent outline-item under which to add the new item, or the parent item's value, or else nil add the new item as a top-level item. Specifying the parent item by its value is typically convenient, but is less efficient since the item must first be looked up from its value. And if multiple items have this same value, then the wrong parent may be found unless the actual parent outline-item is specified.

position indicates the index of the new item among its siblings. Zero (or nil) puts the item above all its siblings, 1 places it below the first sibling, and so on. The special value :end will put the item below all of its siblings.

If no-redisplay is true, the outline will not be redisplayed by this function to reflect the change. You may wish to delay redisplay when there is more than one modification until all modifications are made.

range may be a list of outline-item instances that will become the child items of the newly-created item, or (typically) nil to not add any child items at this time.

kind simply sets the kind property of the new item.

If no item was successfully added, then nil is returned. Otherwise two values are returned: (1) the outline-item that was added, and (2) the index of the new item within all currently visible items. (The index will be nil if the new item is not visible because the parent item is closed.)

See also add-sibling-outline-item, add-child-outline-item, remove-outline-item-value and outline-item-added.


add-row

Generic Function, cg package

Arguments: parent-section new-subsection &optional (index 0)

Adds a grid-row to the grid-row-section specified by parent-section and at the specified index among the rows of that section. An index of zero indicates the first (topmost) position. A huge number can be used for index to add to the end.

Alternately, (setf subsections) can be called to replace the entire set of rows of the row section.

See the description of the grid-widget class.


add-sibling-outline-item

Generic Function, cg package

Arguments: outline &key value

Creates an outline-item that has the specified value, and adds it to the specified outline as a sibling of the currently selected item, if any, and otherwise as a top-level item. The item will be positioned just after the selected item when there is one, and otherwise at the very top of the outline.

This function is a specialization of the more general function add-outline-item-value, and could be used directly for an interactive command to create a sibling of the selected item.


add-status-bar

Generic Function, cg package

Arguments: window &optional status-bar (number-of-lines (status-bar-number-of-lines window)) (font (status-bar-font window)) status-bar-class-name

Creates a status-bar dialog pane on window, unless there is already one there. (Only a single status-bar pane can be added to a window.) Re-sizes any other child windows on window in order to make room for the status-bar. Also moves any widgets (if on a dialog) upward to make room.

The status bar added is an instance of the status-bar class. You may wish to use a common-status-bar, in which case use add-common-status-bar.

The arguments are:


add-tab

Generic Function, cg package

Arguments: tab-control tab-info-or-name label &key (index -1)

Adds a tab to a tab-control at a specified position and displaying a specified label.

tab-control is the existing tab-control widget to which the tab will be added.

tab-info-or-name is either an existing tab-info instance or a symbol to name a new tab. If a symbol, a new instance of the tab-info class having that name will be automatically created. If a tab-info instance, it may be an instance either of the tab-info class itself or of an application-defined subclass of tab-info.

label is a string to display on the tab. If tab-info-or-name* is a *tab-info object that already has a *label property, then nil may be passed here to use the *existing label.

index indicates the position at which to add the new tab. Zero will place the new tab at the leftmost position, 1 at the next leftmost position, and so on. A negative number indicates a position from the right end of the existing tabs, where -1 is the last (rightmost) position, -2 the next rightmost position, and so on. The default is -1 to add the new tab to the right of all of the existing tabs.

See the description of the tab-control class/control.


add-to-menu

Generic Function, cg package

Arguments: menu menu-item &key position after (at-end t)

Adds menu-item to menu at a specified position among the current menu-items or after a menu-item given as the value of after. at-end is obsolete (use :position :end).

Returns the menu-item that was passed in after adding it to menu.

The arguments are:

The position of the menu-item is determined by the after argument if it specifies a menu-item that is present in menu, and otherwise by the position argument. Note that a menu-item should only be added to one menu. If a similar menu-item must appear in more than one menu, create copies (by calling (make-instance 'menu-item) with identical arguments or with copy-menu-item) as necessary.

See also open-menu.

Backward compatibility note: All releases after 5.0 replace the at-end argument with the position and after arguments, but at-end will still work for backward compatibility. If at-end is true (and position and after are unspecified), then the menu-item is placed at the bottom of the menu, and otherwise at the top. at-end should not be specified simultaneously with either position or after; an error will be signaled if this is done.


add-toolbar

Generic Function, cg package

Arguments: window* &optional *toolbar no-resize-toolbar no-resize-child-windows

Creates a toolbar dialog pane on window. The new toolbar is added just below any existing toolbars on the window, unless no-resize-toolbar is true, in which case the toolbar retains its current coordinates (which would make sense only for an existing toolbar that's passed in). Any other child panes are shaped smaller to make room for the new toolbar, unless no-resize-child-windows is true. Any components (if the window is a dialog) are moved lower to make room for the toolbar.

The new toolbar is created without any controls on it initially, unless you pass the optional toolbar argument to add a pre-existing toolbar dialog to the window rather than creating a new one. A pre-existing toolbar can be either a toolbar that was removed from this or another window, or an arbitrary toolbar created by calling make-window and specifying the toolbar class.

Alternately, you can use the Integrated Development Environment to build a window complete with toolbar and toolbar widgets that will be recreated all at once.


add-tray-item

Generic Function, cg package

Argument stray-item &key window

Adds the specified tray-item to the system tray unless it is there already, in which case nothing is done. in-tray-p returns whether a tray-item is currently in the tray, and remove-tray-item removes a tray-item from the tray. A tray-item may be added and removed any number of times.

tray-item must be an instance of the tray-item class, as created with make-instance.

If window is specified, it should be the window that will be passed to tray-item-message when mouse events occur on the tray-item. If nil, then the application's frontmost top-level window whose state is either :normal or :maximized will be used; an error will be signaled if there is no such window.

An application would typically specify an icon for the tray-item before adding it to the tray. See tray-item-icon.

It is recommended that remove-tray-item be called on the tray-item before the application exits or its window is closed. This is not necessary, but the icon may otherwise continue to appear in the tray until the end user moves the mouse over it.

See the description of the tray-item class for an example.


alignment

Generic Function, cg package

Arguments: list-view

Determines how icons in list-view are laid out when they are arranged into a rectangular array. Such arrangement is done only when the layout-style of the argument list-view is either :small-icon or :large-icon. (See arrange-icons and auto-arrange.)

The value can be :top or :left. The default is :top. When the value is :top, the icons are first laid out in a row along the top of the window, then in a second row below that, and so on. When the value is :left, then the icons are first laid out in a column along the left side of the window, then in a second column beside that, and so on.

See list-view.


allow-during-modality

Generic Function, cg package

Arguments: menu-item

Determines whether the keyboard shortcut for this menu-item may be used while a modal dialog is invoked. Generally this property should be turned on only for those menu commands that may be applied within the context of a modal dialog and without requiring interaction with other windows, since the user should be interacting only with the modal dialog as long as it is shown.

allow-during-modality is a property of the menu-item class.


ancestor-background-color

Generic Function, cg package

Arguments: outline

Returns the value of the ancestor-background-color property of an outline control. The value may be specified at creation time by passing the ancestor-background-color initarg to make-instance, or any time later by calling (setf ancestor-background-color)).

This is the color in which the background of ancestor outline-items of the currently selected item will be drawn if the highlight-ancestors property is true.

The value should always be an RGB color object, as made with make-rgb. The default value is a "slate blue" made with (make-rgb :red 235 :green 235 :blue 250).


animate-color-number

Generic Function, cg package

Arguments: stream color-number rgb

Tells the operating system to insert the rgb color (see make-rgb) which is the rgb argument into the palette of stream at index color-number. Further, the OS is told not to share this color with other palettes because it needs to be reserved for color switching. stream should be a cg-stream.


ansi-fixed-font

Function, cg package

Arguments:

Returns a standard fixed-width font provided by the operating system. This is the suggested default fixed-width font.


ansi-var-font

Function, cg package

Arguments:

Returns a standard variable-width font provided by the operating system. This is the suggested default variable-width font.


antialias-lines

Generic Function, cg package

Arguments: widget

This property has an effect only on the Windows platform.

This property of various widgets determines the value that *antialiasing* will have while drawing lines and filling areas in the widget. See *antialiasing* for an explanation of its effect.

The value can be set at creation time by passing the :antialias-lines initarg to make-instance, or any time later by calling (setf antialias-lines).

This is a property of chart-widget, plot-widget, lamp, grid-widget, and node-pane-mixin. For the grid-widget, *antialiasing* will be bound only by the built-in draw-cell methods; you would need to bind it in your own draw-cell methods to effect antialiasing in custom-drawn grid cells.


antialias-text

Generic Function, cg package

Arguments: widget

This property has an effect only on the Windows platform.

This property of various widgets determines the value that *antialiasing* will have while drawing text in the widget. See *antialiasing* for an explanation of its effect.

The value can be set at creation time by passing the :antialias-text initarg to make-instance, or any time later by calling (setf antialias-text).

This is a property of scrolling-static-text, outline, chart-widget, plot-widget, lamp, grid-widget, and node-pane-mixin. For the grid-widget, *antialiasing* will be bound only by the built-in draw-cell methods; you would need to bind it in your own draw-cell methods to effect antialiasing in custom-drawn grid cells.


app

Generic Function, cg package

Arguments: system

An app is an object containing internal information about the currently-running lisp application.

(app *system*) (see app and *system*) returns the app object for the currently-running lisp application. This property is read-only. It is a property of the system class.


application-icon

Function, cg package

Arguments:

Returns a pre-defined icon showing a square with blank interior. In CG/JS mode this is actually a pixmap, which can be used as an icon in that mode. In Windows desktop mode it is the icon that is the value of the application-icon variable.


application-type

Generic Function, cg package

This function is no longer supported. It returned the application type of its project argument, but only standard-exe is currently supported.


arrange-icons

Generic Function, cg package

Arguments: list-view &key align

This function moves the icons in a list-view control if needed so that they are aligned horizontally and vertically and spaced equally. This is done only if the current layout-style is either :large-icon or :small-icon, since otherwise the items always appear as a single vertical list. The items will be arranged according to the value of the alignment property of the list-view.

align determines the value of the alignment property that is in effect when the arrangement is done. If either :left or :top, then the alignment property is first set to this value, and the arrangement is then done using that alignment value. If nil, then the current type of alignment is used.

This function will probably be needed only if the list-view is resized and its auto-arrange property is false, or if the function (setf list-view-item-position) has been used on some of the list-view's items.

See list-view.


ask-save-changes

Generic Function, cg package

Arguments: window

Pops up a dialog containing three buttons asking the user whether to save changes made to window.

Returns one of :yes, :no or :cancel.

The position of the dialog when displayed is controlled by position-utility-dialog.


ask-user-for-choice

Function, cg package

Arguments: prompt button1 &optional button2 button3 button4 title stream &key topmost

This is another version of pop-up-message-dialog. A dialog is displayed with as many buttons (one, two, three, or four) as are specified non-nil. The user clicks on a button and the value of that button (the value specified as the argument) is returned.

If the user cancels the dialog by clicking on the close box or pressing the Escape key, ask-user-for-choice returns the same as if the rightmost non-nil button was clicked. If the user hits Enter, the value of button1 is returned. That is, the leftmost button (button1, which must be non-nil) acts as the default button and the rightmost non-nil button acts as the cancel button. If there is only one button (button2, button3, and button4 are all nil), then any action (clicking on it, pressing Escape, pressing Enter, or clicking on the close button) causes button1 to be returned.

If you have more than four choices, you can use ask-user-for-choice-from-list.

The arguments are:

The position of the dialog when displayed is controlled by position-utility-dialog.


ask-user-for-choice-from-list

Function, cg package

Arguments: title choice-list &key stream initial-value allow-multiple simple-click-toggle (on-print 'princ-to-string) on-change topmost width height on-list-item-mouse-in dialog-exterior-box

Displays a modal dialog with title title offering the choices in choice-list along with OK and Cancel buttons. Two values are returned: the value or list of values (if allow-multiple is true) chosen and t if the OK button is clicked; nil and nil if the Cancel button is clicked. (The second returned value allows the program to distinguish between the user selecting the value nil and canceling the dialog.)

The keyword arguments are:

An alternative way to ask the user for a choice from a list, especially if the list of choices is small, is to call pop-up-menu, pop-up-lettered-menu, or pop-up-shortcut-menu. For four choices or fewer, ask-user-for-choice may be used. See also yes-no-or-cancel-list.


ask-user-for-color

Function, cg package

Arguments: &key initial-color (title "Select a Color") (prompt "Use the widgets to specify a new color.") show-custom-colors disable-custom-colors stream

Displays a dialog for specifying a color value. Returns an RGB color value for the color that was selected, or initial-color if no color was selected. Except if the user cancels the interaction (by pressing the Cancel button on the dialog), then nil is returned.

initial-color should be an RGB color value (such as created by make-rgb), or else nil to default to some unspecified color.

title should be a string to display in the title-bar of the dialog. This has no effect in Windows desktop mode, where the Microsoft dialog does not support it. This parameter was added in release 11.0.

prompt should be a string to display in the body of the dialog to instruct the user what to do. This is used only in CG/JS mode. This parameter was added in release 11.0.

If show-custom-colors is specified true, then an extra section of the dialog that allows users to define custom colors in addition to the standard set is displayed initially. If nil, then the extra section is displayed only if the user clicks the button whose appearance is controlled by the next argument. This is implemented only in Windows desktop mode.

If disable-custom-colors is specified true, then the button that brings up an extra section of the dialog that shows custom colors is masked. This is implemented only in Windows desktop mode.

stream is the owner window for the dialog. This window and all of its owned windows and their descendants will be unavailable to the end user while the color dialog is present. stream defaults to the stream returned by selected-window-or-screen. It is also valid to specify (screen *system*) (see screen), which means that the dialog will not have an owner window and therefore will not disable any windows.


ask-user-for-date

function, cg package

Arguments: &key initial-date (get-universal-time)) (title "Select a Date") (calendar-mode :month) (stream (selected-window-or-screen))

This function displays a modal dialog that contains a calendar widget, allowing the user to select a date.

initial-date is a universal time integer for the date that will initially be selected. The default is today.

title is a string to display in the title bar of the dialog. The default is "Select a Date".

calendar-mode is a keyword symbol for the type of date range that the calendar will initially display. See the calendar-mode property for the valid values. The default is :month to display one full month of individual dates. The value may also be nil to show the calendar in the mode that it was in when the user last exited the dialog.

stream is the owner window (or the screen) on which the dialog will be displayed. The default is the currently-selected window, if any, and otherwise the screen.

If the user cancels the dialog, then nil is returned. Otherwise four values are returned, all integers.

  1. A universal time for the date that the user selected.

  2. The year of that universal time.

  3. The month (1 to 12) of that universal time.

  4. The date (1 to 31) of that universal time.

See the calendar class for general information on the widget that is shown in the dialog. An additional feature of this dialog is that the user can double-click a date to immediately return that date from the dialog, as an alternative to first selecting a date and then either pressing the OK button or pressing the Enter key.


ask-user-for-directory

Function, cg package

Arguments: &key (prompt "Select a folder.") (stream (selected-window-or-screen)) root dont-go-below-domain browse-include-files include-edit-box new-dialog-style

Displays a dialog where the user can select an existing directory (also known as a folder).

The newer function ask-user-for-new-or-existing-directory has more options than this one and works the same on all platforms, and so may be a better choice in most cases. On the other hand, on the Windows platform this function will show the dialog that is provided by Microsoft, with its native look and feel. In CG/JS mode, this function simply calls ask-user-for-new-or-existing-directory, because there is no native JavaScript dialog to invoke instead. The rest of the description of this function is specific to Windows desktop mode.

The chosen directory is returned as a pathname object. Note that the directory is stored in a buffer, and if the buffer is too small then an error will be signaled. The buffer size is determined by file-selection-buffer-size. The default size is large enough to hold at least 12 pathnames so this should not be a problem for this function, which returns one pathname only.

Note too that it is not possible to specify the initially-selected directory or which subdirectories are initially open in the hierarchy that is presented.

The arguments are:

See also ask-user-for-existing-pathname and ask-user-for-new-pathname, which ask the user for a file rather than a directory.


ask-user-for-existing-pathname

Function, cg package

Arguments: prompt &key initial-directory initial-name stream allowed-types multiple-p change-current-directory-p share-aware-p default-extension (buffer-size (file-selection-buffer-size (configuration *system*))) title

This function provides the service of prompting for one or more existing pathnames.

If multiple-p is nil (the default), returns the pathname of the selected file, or nil if none was chosen. If multiple-p is true, returns a list of selected files (even if only one is selected) or nil if none is selected. prompt should be a string explaining what is to be done with the selected file (e.g. "Choose file to open").

The arguments are:

This function uses the standard Common Dialog supplied by the platform's underlying windowing system for file selection. Internal Allegro CL file selection dialogs use this function.

See also ask-user-for-new-pathname and ask-user-for-directory. And see file-selection-buffer-size.


ask-user-for-font

Function, cg package

Arguments: &key stream-for-font initial-font fixed-width-only-p minimum-size maximum-size initial-point-size stream

Pops up the Windows Common Dialog for font selection. This function is also used internally by Allegro CL for font selection. If a font is selected, two values are returned: the font selected and the point size specified by the user. (See below for why the point size might be useful.) If s/he cancels, the single value nil is returned.

The arguments are as follows:

When selecting a font, one potential source of confusion is that while Allegro CL specifies font sizes in pixels, the Common Dialog specifies them in points. So the size that you select from the dialog will not be the same as the size value in the returned font object. But the point size specified will be returned as the second returned value -- see the next paragraph. Allegro CL uses pixel-size programmatically so that the same units are used for all sizes associated with a window --fonts, window dimensions, drawing, etc. The point sizes that appear in the Common Dialog, on the other hand, will be similar to those that are familiar from choosing fonts interactively in other applications.

The point size is provided as the second returned value to permit better communication with users. Suppose a user of your application is presented with the dialog displayed by this function and asked to choose a font for use in some table of data that the application will display. Suppose further that the program determines that the font chosen is so large that it will cause line truncation or wrapping. A dialog might be displayed telling the user that the chosen font will cause problems and that s/he might wish to choose a smaller font. Mentioning the point size in that dialog will be more meaningful to users (because it corresponds to the value they actually chose) than mentioning the pixel size, which is a value they likely will not have seen. Note that both the point size and the pixel size are contained in the Windows font structure, from which Allegro CL gets all font information. Allegro CL does not itself derive a pixel size from the point size.


ask-user-for-new-or-existing-directory

Function, cg package

Arguments: &key (owner (selected-window-or-screen)) (type :either) (always-show-text-box t) title prompt position width height (scope :all) (special-folders '((:personal #+mswindows "My Documents" #-mswindows "Home"))) (create-if-new t) initial-directory initial-subdirectory show-initial-directory-siblings (show-local-file-systems t) look-ahead (prompt-for-password-if-needed t) (focus-on-new-subdirectory (eq type :new)) select-file (allowed-types '(("All Files" . "*.*"))) default-extension initial-name close-subtrees-on-close show-initial-directory-children search-network-globally

This function displays a modal dialog that allows the user to specify a new or existing directory (also known as a folder). The directory can be specified either by selecting it in the outline widget, or entering an absolute path namestring in the text-entry widget, or by entering a relative path namestring in the text-entry widget that is relative to the directory that is selected in the outline. It does not matter whether the user types a final slash character after a directory name in the text-entry widget. Help strings at the bottom of the dialog guide the user in specifying a complete path.

Two values are returned: (1) A pathname for the directory that was specified by the user (or nil if the user cancels the dialog), and (2) either t or nil, indicating whether the directory is a new one (that is, nil if there already was a directory at the specified path, and t if there was not).

The arguments are:

Other notes

The dialog displays a file folder for each outline-item that represents an actual directory that may be returned. On Windows, this excludes the two root items for all "Local Disks" and "Network Machines" plus each network share (because only the descendent items of each share represent actual directories). These non-directory items will display a simple triangle icon instead of a file folder.

The OK button on the dialog will be disabled if no directory that may be returned is currently specified. This includes whenever a non-directory outline-item is selected. If the type argument is :existing (and always-show-text-box is true), this also includes when the text-entry widget contains text that does not name an existing directory. And if the type argument is :new, this also includes when the text control for the new subdirectory name is empty or contains an invalid directory name. At these times, the user may not exit the dialog by pressing the OK button or by pressing ENTER, but they may always exit by canceling the dialog (as usual, by pressing the ESCAPE key or the Cancel button or clicking the small close button in the frame).

On Windows, if the directory-selecting dialog that is provided by Microsoft is desired for its native look and feel, then the alternate function ask-user-for-directory will display that dialog. But that function has fewer options than this one.


ask-user-for-new-pathname

Function, cg package

Arguments: prompt &key initial-name initial-directory stream allowed-types multiple-p change-current-directory-p warn-if-exists-p share-aware-p default-extension (buffer-size (file-selection-buffer-size (configuration *system*))) title

This function provides the service of prompting for one or more new pathnames. It displays a file choice dialog which can be used to specify the directory component. Typing the new name into the File field specifies the filename.

If multiple-p is nil (the default), returns the pathname of the selected file, or nil if none was chosen. If multiple-p is true, returns a list of pathnames of the selected files (even if only one is selected) or nil if none is selected. prompt should be a string explaining what is to be done with the selected file (e.g. "Select new filename for file").

The arguments are:

This function uses the standard Common Dialog supplied by the platform's underlying windowing system for file selection. Internal Allegro CL file selection dialogs use this function. See ask-user-for-existing-pathname and ask-user-for-directory. See also file-selection-buffer-size.


ask-user-for-string

Function, cg package

Arguments: prompt string1 option1 option2 &optional prompt2 string2 title stream cursor-at-end multi-line dialog-width

Displays a modal dialog prompting for one or two strings. Prompts for one string if the prompt2 and string2 optional arguments are not supplied or are supplied as nil. Prompts for two strings if prompt2 and string2 are supplied and are true. The string arguments are copied so string1 and (if supplied) string2 will be unchanged after this function returns.

The option1 and option2 arguments provide titles for buttons that appear on the dialog. Clicking a button causes the dialog to exit and the function to return. Each of these values may be either a string or a symbol, and a tilde character (~) in the string or symbol name indicates that the next character should be an underlined access character for the button.

This function returns four values. The first two are the strings as modified by the user except that the second value will be nil when the optional prompt2 and string2 arguments are not passed or are nil. As the third value, ask-user-for-string returns the string which is the value of the selected button argument (that is, option1 or option2 depending on which button the user clicks).

The fourth value indicates whether the user accepted or canceled the dialog. The value is t if the user either clicked the option1 button or pressed the ENTER key, and nil if the user either clicked the option2 button or pressed the ESCAPE key to cancel the dialog. In a sense, this repeats the information in the third returned value, since a string comparison such as

(when (string= third-value "~OK") 
   <process-the-string>)

The fourth value allows a simpler test such as:

(when fourth-value <process-the-string>)

This also removes the need to hardcode the button label twice or to let bind it.

The title argument (if supplied) should be a string and provides the title of the dialog. The prompt, string1, option1, and option2 arguments should also be strings.

The stream argument indicates the owner window for the dialog. It defaults to the stream returned by selected-window-or-screen.

If cursor-at-end is true, then the text cursor will initially be at the end of the initial string, to facilitate extending the suggested string. If nil, then the entire string will initially be selected, to facilitate replacing the string.

multi-line specifies whether the text-editing widgets allow editing multiple lines of text that contain newline characters, rather than only a single line. The functions pop-up-string-dialog and pop-up-strings-dialog also have this option as a keyword parameter, which is nicer than the unfortunate optional arguments of this function that are still used for backward compatibility. Any true value means to use a multi-line widget, and an integer value can be used to also specify the pixel height of the multi-line-editable-text widgets. This parameter was added in release 11.0.

dialog-width is the interior width of the dialog in pixels. The default width is 480. (The height is always determined automatically from the needed heights of the widgets.) This parameter was added in release 11.0.

Note several things:

The position of the dialog when displayed is controlled by position-utility-dialog.

See also pop-up-string-dialog and pop-up-strings-dialog. Their return values include the number of the button pressed and thus it may be easier to know what the user did using those functions rather than this one.

Example

(ask-user-for-string
 "Enter the correct answer and win a beautiful lounge suite."
 "default answer" :~OK :~cancel nil nil "Answer Box"
 (selected-window (screen *system*)))

A typical usage of the returned string or strings would be to pass them to string-search or string-replace.


attachment

Generic Function, cg package

Arguments: window

Returns as four multiple values the attachment properties of window. These determine how window's size changes when its parent is resized. The issue is whether the window should scale with its parent or should stay the same size and whether the distance from a side of the child window to the corresponding side of the parent window should stay constant or should scale with the resizing. The four values are returned by this function (as multiple values). They specify the attachment behavior of the left, the top, the right, and the bottom of window, respectively.

The possible values for :left-attachment and :right-attachment are the keywords :left, :right, and :scale. :left means maintain the same distance from the parent's left side as before the parent was resized -- if the distance was 30 pixels before it is 30 pixels after the parent's resizing. :right means keep the distance to the right side constant. :scale means keep the ratio of the distances from the left and right sides constant -- if the side was half way between before, it is half way between after.

The possible values for the :top-attachment and :bottom-attachment are the keywords :top, :bottom, and :scale. :top means maintain the same distance from the parent's top as before the parent was resized -- if the distance was 30 pixels before it is 30 pixels after the parent's resizing. :bottom means keep the distance to the bottom constant. :scale means keep the ratio of the distances from the top and bottom sides constant -- if the side was half way between before, it is half way between after.

bottom-attachment, left-attachment, right-attachment, and top-attachment return the individual attachment properties.


auto-arrange

Generic Function, cg package

Arguments: list-view

A boolean value indicating whether a list-view control will automatically arrange its list-view-items back into a rectangular array whenever an item is moved or the list-view is resized. This is done only when the layout-style of the list-view is either :small-icon or :large-icon. If nil (the default), then no automatic arrangement is done. If t, then automatic arrangement is done. The arrangement is done when setting this property to t as well.

For example, if the attachment properties (top-attachment, etc.) of a list-view control are set up so that the list-view is resized whenever the end user resizes its parent dialog, then the icons will be re-arranged to fill the new size of the list-view control if auto-arrange has been turned on.

A current incapacity of the list-view control is that it is not allowing the end user to drag list-view-items to new arbitrary positions, as it should when the layout-style is either :small-icon or :large-icon. But if a list-view-item is moved programmatically by calling (setf list-view-item-position), then auto-arrangement will still occur, and place the item back into the rectangular array position that is closest to the position to which the list-view-item was moved.

See list-view.


auto-size

Generic Function, cg package

Arguments: column

When called on a list-view-column, modifies the width of the column so that the longest string in the column has just enough room. When called on a list-view control, auto-sizes all of its columns at once. See the description of the list-view control.


automatic-font-changing

Generic Function, cg package

Arguments: text-edit-pane

This function has an effect only on the Windows platform.

Returns true or nil to indicate whether text-edit-pane (a text-edit-pane) will automatically switch to a different font when needed in order to properly display particular characters that are inserted into it. The value may be set when creating the window by passing an automatic-font-changing initarg to make-window, or any time later by calling (setf automatic-font-changing). The default value is nil.

This feature is typically used when the text-edit-pane might contain multibyte characters that are not available in some fonts. It can also be useful for Asian characters even when the text-edit-pane's official font contains the characters if it does not provide sufficient horizontal space to display wider characters readably.

If this features changes parts of the text to different fonts, CG does not actually know about that, and font will still return the single official font that was assigned to it by the application. On the other hand, get-character-format will return the name of the font face that is actually in use at the current text cursor position.

This function is a direct hook into the IMF_AUTOFONT option of Microsoft's RichEdit control. Font changes that this option makes may be rather unpredictable, and so setting the font property of a text-edit-pane to a font that you know is adequate may be preferrable to using this option.

See also dual-fonts-for-languages.


automatic-sizing

Generic Function, cg package

Arguments: calendar-widget

This property of a calendar widget determines whether the width and height of the widget will be automatically adjusted so that it is just big enough to fit the widget's contents when it's drawn according to its various properties. Properties that can affect the size include row-padding, column-padding, border-margin, title-margin, and calendar-title-font. Further, the pixmaps used to identify where to click to get the next and previous calendar pages (identified by increment-pixmap-name and decrement-pixmap-name) also affect sizing.

If the value is true, then automatic resizing will be done when the widget is created and when any of those properties are modified thereafter. If the value is nil, then the calendar cells will be spread evenly over the available area instead.

See also the calendar class and the function ask-user-for-date.


available

Generic Function, cg package

Arguments: standard-object

Returns true or nil as standard-object (typically a component or menu-item) is or is not available. An unavailable object cannot be selected or chosen. It is usually displayed with a visual clue that it is unavailable (i.e. it is dimmed or grayed out).

The value returned can be changed with setf and this function.


available-clipboard-formats

Function, cg package

Arguments:

Returns a list of the clipboard formats that are currently on the Windows clipboard. When a copy is done, applications typically clear all values from the clipboard and then post only those formats that apply to the object being copied. If rich text was most recently copied to the clipboard, then the list returned from this function may be (:text :rich-text). The only valid clipboard formats at this time are :text, :rich-text, and :pixmap. The :pixmap format reflects the "device-independent bitmap" Windows clipboard format; Common Graphics does not support the "device-dependent bitmap" format.

See cg-rich-text.html for information about rich text editing in Common Graphics. See also cg-clipboard.html.


available-reader

Generic Function, cg package

Arguments: grid-column

Returns a function that returns whether each of the grid cells in a particular column of a grid-widget is currently accessible to the user, or else returns nil to determine the availability in other ways (see cell-available). The default value is nil.

The available-reader function is a property of a particular grid-column, and is called once for each grid-row that intersects that column to determine the availability of the cell at the intersection of that row and column. The function should take one argument, which is the data-object of a grid-row. If the attribute represented by the grid-column should currently be accessible to the user for the data-object that is passed to the function, then the function should return true, and otherwise it should return nil. When not available, a grid-cell appears grayed out and its value may not be modified by the user.

This property value may be specified as either a function name symbol (which would be more debuggable), or a function object (which may be slightly faster, though probably insignificantly), or nil.

Example: In the employee grid example, each grid-row represents an employee. If the "Full Time?" grid-column had an available-reader function, then the system would periodically pass an employee to that function, and the function should return true if the "Full Time?" cell for that employee should currently be accessible to the user. The employee grid example can be found on the Examples tab of the Navigator dialog.

NOTE: An application does not call the available-reader function; it supplies the available-reader function by calling (setf available-reader) or by passing the :available-reader initarg when calling make-instance to create a grid-column. The specified function is then called automatically by the system as needed.

available-reader is a property of the grid-column and row-header-column.


axis-color

Generic Function, cg package

Arguments: chart-axis

Returns the value of the axis-color property of a chart-axis. The value may be set at creation time by passing the :axis-color initarg, or any time later by calling (setf axis-color).

axis-color is the color that is used to draw a chart-axis of a chart-widget, including its tic marks. The value should be an RGB color object (see make-rgb) or else nil to default to the system-edge-shadow-color. The default value is nil.

The text on an axis is drawn in other colors. See axis-label-color, major-label-color, and minor-label-color.

See chart-widget and also cg-chart-widget.html.


axis-label

Generic Function, cg package

Arguments: chart-axis

Returns the value of the axis-label property of a chart-axis. The value may be set at creation time by passing the :axis-label initarg, or any time later by calling (setf axis-label).

axis-label is the label that is drawn along the length of a chart-axis on a chart-widget to indicate the meaning of the axis. The value should be a string or else nil to avoid drawing a main label on the axis at all. The default value is nil.

The string will be drawn in the axis-label-color and axis-label-font of the axis.

The chart will provide space for the label only when it is a string rather than nil. Only space for a single line of text is provided, unlike chart properties such as title, subtitle, and footnote, so the text should be no longer than the axis itself.

See chart-widget and also cg-chart-widget.html.


axis-label-color

Generic Function, cg package

Arguments: chart-axis

Returns the value of the axis-label-color property of a chart-axis. The value may be set at creation time by passing the :axis-label-color initarg, or any time later by calling (setf axis-label-color).

axis-label-color is the color that is used to draw the single axis-label along a chart-axis of a chart-widget. The value should be an RGB object (see make-rgb). The default value is the value of black.

The tic mark labels are drawn with the major-label-color and minor-label-color properties.

See chart-widget and also cg-chart-widget.html.


axis-label-font

Generic Function, cg package

Arguments: chart-axis

Returns the value of the axis-label-font property of a chart-axis. The value may be set at creation time by passing the :axis-label-font initarg, or any time later by calling (setf axis-label-font))

axis-label-font is the font that is used to draw the single label along a chart-axis of a chart-widget. The value should be a font object (see make-font-ex). The default value is the font returned by (make-font-ex nil "Arial" 14).

The tic mark labels are drawn with the major-label-font and minor-label-font properties.

See chart-widget and also cg-chart-widget.html.


axis-width

Generic Function, cg package

Arguments: chart-axis

Returns the value of the axis-width property of a chart-axis. The value may be set at creation time by passing the :axis-width initarg, or any time later by calling (setf axis-width).

The thickness, measured in pixels, of the stem of a chart-axis of a chart-widget. The value should be a non-negative integer. The default value is 3.

Zero will avoid drawing the axis stem altogether, though the axis tic marks will still be drawn according to major-tic-length, major-tic-width, minor-tic-length, and minor-tic-width.

See chart-widget and also cg-chart-widget.html.


background-color

Generic Function, cg package

Arguments: *standard-object *

Returns the background color for standard-object if one has been specified for it, and otherwise returns nil. (By contrast, effective-background-color will always return a color, by calling default-background-color when background-color returns nil.)

The background-color is the color that is used to erase the object's drawing area (such as by clear-page) before its graphical content is drawn in the object's foreground-color. It is also used for drawing by functions such as erase-line and erase-contents-box. foreground-color and background-color apply to windows, dialog-items, button-infos (of a multi-picture-button), and outline-items (of an outline).

A background color may be specified either by calling (setf background-color) or by passing the background-color initarg to make-instance or make-window when creating the object. The value may be either an RGB instance (see make-rgb), nil, or t. nil means to use the default-background-color for the object. t means to use the background color of the parent of the object, if there is a parent, and otherwise use the default-background-color of the object.

The value cannot be an HLS color, as returned by make-hls. If you use HLS colors, apply hls-to-rgb to them before setting this property, and call rgb-to-hls to get the HLS equivalent of an RGB value.

It is typical to leave the background-color of an object nil. In that case, the color returned by default-background-color will be used. If the default methods for that generic function have not been overridden, default-background-color will return a system color such as the one returned by system-background-color or system-dialog-background-color (depending on whether the object is or is not an instance of dialog-mixin). This causes your application to use the end user's preferred colors that they have selected in the Windows Control Panel.

Some widgets that are supplied by the underlying window system will not allow you to change their background color. This is usually true when there is normally no need to use a non-default color.

The actual RGB instance that is passed to (setf background-color) is retained to be returned later by background-color, so an application should not modify an RGB instance while it is assigned to an object. A single RGB instance may be assigned to any number of objects, however.

In earlier releases, this generic function had an optional argument, result-rgb, which was already deprecated and unused. Starting in release 7.0, that argument is no longer supported. Code which includes that argument will signal an error. The error can be fixed by removing any reference to a second, optional argument.

See also with-background-color, a convenient macro that temporarily changes the background color while a body of code is executed.


background-color-one

Generic Function, cg package

Arguments: grid-row-section

Returns (or sets with setf) one of two background colors (see make-rgb) that will be used when drawing the rows of grid-row-section (a grid-row-section). The value may be nil to not specify the color here and instead defer to whatever cell-background-color methods return.

Typically both (or neither) background-color-one and background-color-two are specified, in which case successive rows of the row-section will alternately draw the two colors. This is sometimes called banding.


background-color-two

Generic Function, cg package

Arguments: grid-row-section

Returns (or sets with setf) one of two background colors (see make-rgb) that will be used when drawing the rows of grid-row-section (a grid-row-section). The value may be nil to not specify the color here and instead defer to whatever cell-background-color methods return.

Typically both (or neither) background-color-one and background-color-two are specified, in which case successive rows of the row-section will alternately draw the two colors. This is sometimes called banding.


background-texture

Generic Function, cg package

Arguments: stream

Returns (or sets with setf) the background-texture of a stream. The background-texture is used by drawing functions that erase an area of a stream, and may be used to "erase" with a pattern rather than a solid color. Functions that use the background-texture of a stream include clear-page, erase-contents-box, erase-contents-circle, erase-contents-circle-sector, erase-contents-ellipse, erase-contents-ellipse-sector, erase-contents-polygon, and erase-contents-rounded-box.

The value should be a pixmap or special symbol, as with fill-texture. See fill-texture for more information and a list of the special symbols.


bad-drop

Generic Function, cg package

Arguments: drag-widget drop-widget position

Called when a drop is done over a control where droppable-p indicates that the drop is not allowed.

The default methods simply display a message in the Allegro CL status-bar in the development environment, and do nothing at runtime.


bar-border-colors

Generic Function, cg package

Arguments: bar-chart-view

Returns the value of the bar-border-colors property of a bar-chart-view. The value may be set at creation time by passing the bar-border-colors initarg, or any time later by calling (setf bar-border-colors).

The colors that are used to draw the borders of the bars of a bar-chart-view in a chart-widget. The value should be a sequence (list or vector) of RGB objects (see make-rgb) and/or symbols that are globally bound to RGB objects. The default value is a list of the symbol black.

If the value is nil, then no borders are drawn on the bars. Otherwise, the first object in the chart-widget's sequence of chart-objects is drawn with the first color, the second object with the second color, and so on. If there are fewer colors in the list than there are chart-objects, then the drawing code will cycle back through the list of colors as needed.

See also bar-colors.

See chart-widget and also cg-chart-widget.html.


bar-chart-view

Generic Function, cg package

Arguments: chart-widget

Returns the value of the bar-chart-view property of a chart-widget. The value may be set at creation time by passing the :bar-chart-view initarg, or any time later by calling (setf bar-chart-view).

bar-chart-view is the chart-view that draws a chart-widget's data as a bar chart. The value is an instance of the bar-chart-view class, and holds properties that are used whenever the chart-view property of the chart-widget is :bar.

The value of this property is always a bar-chart-view instance, even when this view is never used. If you do not pass a bar-chart-view instance as the value of the :bar-chart-view initarg when creating a chart-widget, then a default instance is created automatically.

See chart-widget and also cg-chart-widget.html.


bar-colors

Generic Function, cg package

Arguments: bar-chart-view

Returns the value of the bar-colors property of a bar-chart-view. The value may be set at creation time by passing the bar-colors initarg, or any time later by calling (setf bar-colors).

The colors that are used to fill the interior of the bars of a bar-chart-view in a chart-widget. The value should be a sequence (list or vector) of RGB objects (see make-rgb) and/or symbols that are globally bound to RGB objects. The default value is a list returned by the following (the symbols name pre-defined colors, see make-rgb):

(list 'light-blue 'green 'light-red 'yellow
      'cyan 'magenta 'blue 'dark-green 'red
      'dark-cyan 'dark-yellow 'gray 'dark-gray)

If the value is nil, then the bars are not filled and will be transparent. Otherwise, the first object in the chart-widget's sequence of chart-objects is drawn with the first color, the second object with the second color, and so on. If there are fewer colors in the list than there are chart-objects, then the drawing code will cycle back through the list of colors as needed.

This property and other bar-chart-view properties are used only when the chart-view property of the chart-widget is :bar to display the bar-chart-view.

See also bar-border-colors and bar-fill-textures.

See chart-widget and also cg-chart-widget.html.


bar-fill-textures

Generic Function, cg package

Arguments: bar-chart-view

Returns the value of the bar-fill-textures property of a bar-chart-view. The value may be set at creation time by passing the bar-fill-textures initarg, or any time later by calling (setf bar-fill-textures).

The textures that are used to fill the interior of the bars of a bar-chart-view in a chart-widget. The value should be a sequence (list or vector) of values that are valid for the fill-texture property of a graphical-stream (such as arbitrary pixmaps), and/or symbols that are globally bound to such values. The default value is nil.

If the value is nil, then no fill textures will be used and the bars will be filled with solid colors from the bar-colors property. Otherwise, the first object in the chart-widget's sequence of chart-objects is drawn with the first texture, the second object with the second texture, and so on. If there are fewer textures in the list than there are chart-objects, then the drawing code will cycle back through the list of textures as needed.

See chart-widget and also cg-chart-widget.html.


bar-gradient-blend

Generic Function, cg package

Arguments: bar-chart-view

This property has an effect only on the Windows platform.

This property of bar-chart-view determines the value that *color-gradient-blend* will have while filling bars in the bar chart. See *color-gradient-blend* for an explanation of its effect and the valid values.

The value can be set at creation time by passing the :bar-gradient-blend initarg to make-instance, or any time later by calling (setf bar-gradient-blend).


bar-gradient-direction

Generic Function, cg package

Arguments: bar-chart-view

This property has an effect only on the Windows platform.

This property of bar-chart-view determines the value that *color-gradient-direction* will have while filling bars in the bar chart. See *color-gradient-direction* for an explanation of its effect and the valid values.

The value can be set at creation time by passing the :bar-gradient-direction initarg to make-instance, or any time later by calling (setf bar-gradient-direction).


bar-gradient-filling

Generic Function, cg package

Arguments: bar-chart-view

This property has an effect only on the Windows platform.

This property of bar-chart-view determines the value that *color-gradient-filling* will have while filling bars in the bar chart. See *color-gradient-filling* for an explanation of its effect and the valid values.

The value can be set at creation time by passing the :bar-gradient-filling initarg to make-instance, or any time later by calling (setf bar-gradient-filling).


bar-gradient-intensity

Generic Function, cg package

Arguments: bar-chart-view

This property has an effect only on the Windows platform.

This property of bar-chart-view determines the value that *color-gradient-intensity* will have while filling bar in the bar chart. See *color-gradient-intensity* for an explanation of its effect and the valid values.

The value can be set at creation time by passing the :bar-gradient-intensity initarg to make-instance, or any time later by calling (setf bar-gradient-intensity).


bar-spacing

Generic Function, cg package

Arguments: bar-chart-view

Returns the value of the bar-spacing property of a bar-chart-view. The value may be set at creation time by passing the bar-spacing initarg, or any time later by calling (setf bar-spacing).

The minimum distance, measured in pixels, between the bars of successive chart items of a bar-chart-view in a chart-widget. The value should be a non-negative integer. The default value is 16.

The actual distance will be greater if needed to prevent tic labels on the item-axis from overlapping each other. See major-label-min-spacing and major-label-wrapping.

When there are multiple side-by-side bars for each chart item (which is when there are multiple chart-objects and the values-are-stacked property is nil), then the side-by-side bars for a single chart item are always adjacent to each other, and this value is the distance between the groups of bars for successive chart items.

If fit-chart-items is true, then this value will be scaled proportionally with other sizing properties to make all data fit in view.

See also bar-width and value-spacing.

See chart-widget and also cg-chart-widget.html.


bar-thickness

Generic Function, cg package

Arguments: split-bar

Returns the bar-thickness property of a split-bar widget. The value may be set at creation time by passing the :bar-thickness initarg to make-instance, or any time later by call (setf bar-thickness).

This is the actual thickness of the split-bar widget, measured in pixels. It determines the size of the area in which the user can click the mouse to initiate a drag. It should be thick enough to allow the user to easily click on it. The value should be a positive integer. The default value is 9. The value may be set at creation time by passing the :bar-thickness initarg to make-instance, or any time later by call (setf bar-thickness).

The visible bar will be drawn at this thickness when it is not being dragged, unless the draw-at-dragging-thickness property is true. The thickness of the visible bar while dragging is specified with the dragging-thickness property.


bar-width

Generic Function, cg package

Arguments: bar-chart-view

Returns the value of the bar-width property of a bar-chart-view. The value may be set at creation time by passing the bar-width initarg, or any time later by calling (setf bar-width).

The width, measured in pixels, of the bars of a bar-chart-view in a chart-widget. The value should be a positive integer. The default value is 12.

When there are multiple side-by-side bars for each chart item (which is when there are multiple chart-objects and the values-are-stacked property is nil), this is the width of a single bar rather than the width of the group of side-by-side bars.

If fit-chart-items is true, then this value will be scaled proportionally with other sizing properties to make all data fit in view.

See also bar-spacing.

See chart-widget and also .


base-line-color

Generic Function, cg package

Arguments: bar-chart-view

Returns the value of the base-line-color property of a bar-chart-view. The value may be set at creation time by passing the base-line-color initarg, or any time later by calling (setf base-line-color).

The color in which a line is drawn at the base-value of a bar-chart-view in a chart-widget. The value should be an RGB object (see make-rgb). The default value is the color returned by (make-rgb :red 140 :green 180 :blue 220).

This property is used only when the base-line-drawn property is true.

See chart-widget and also cg-chart-widget.html.


base-line-drawn

Generic Function, cg package

Arguments: bar-chart-view

Returns the value of the base-line-drawn property of a bar-chart-view. The value may be set at creation time by passing the base-line-drawn initarg, or any time later by calling (setf base-line-drawn).

A boolean value indicating whether a line is drawn at the base-value of a bar-chart-view in a chart-widget. The default value is nil.

When true, a line is drawn across the body of the chart-widget parallel to the item-axis and at the base-value of the bar-chart-view. The line's thickness will be the base-line-width of the bar-chart-view and its color will be the base-line-color.

If the base-value is equal to the range-bottom or range-top of the value-axis, or if the base-value is outside that range, then the base line is never drawn.

See chart-widget and also .


base-line-width

Generic Function, cg package

Arguments: bar-chart-view

Returns the value of the base-line-width property of a bar-chart-view. The value may be set at creation time by passing the base-line-width initarg, or any time later by calling (setf base-line-width).

The thickness, measured in pixels, of a line that is drawn at the base-value of a bar-chart-view in a chart-widget. The value should be a positive integer. The default value is 3.

This property is used only when the base-line-drawn property is true.

See chart-widget and also cg-chart-widget.html.


base-value

Generic Function, cg package

Arguments: bar-chart-view

Returns the value of the base-value property of a bar-chart-view. The value may be set at creation time by passing the base-value initarg, or any time later by calling (setf base-value).

The default value for the start of each bar in bar-chart-view in a chart-widget. The value should be a real number. The default value is zero.

Each bar in a bar-chart-view starts at one value on the value-axis and ends at another value. The ending value of a bar is always the main data value for a chart item / chart object pairing that a single bar represents. A "main data value" is the one that is passed as the value argument to set-chart-value or returned from a chart-value-returner function when the value-type argument is :value. The starting value of a bar will be the from-value if one was supplied for the bar, and otherwise it will default to the base-value of the bar-chart-view. The base-value defaults to zero, so every bar by default will start at zero on the value-axis and end at the main value for the bar.

See chart-widget and also .


beep

Generic Function, cg package

Arguments: &optional stream duration

Causes the computer to beep audibly to get the user's attention. The arguments are ignored (they provide backward-compatibility but have no function in the current release).

CG/JS Note: When running in CG/JS mode, the variables *beep-loudness*, *beep-duration*, and *beep-frequency* affect the sound that is produced.


begin-drawing-path

Generic Function, cg package

Arguments: stream

Begins collecting subsequent line-drawing function calls on stream into a "path". Must be followed by a call to end-drawing-path at some point, which actually draws the entire path. stream should be a cg-stream.

A path is useful for filling a collection of lines and curves as a unit.

To ensure that end-drawing-path is always called for each call to begin-drawing-path, it is convenient to use with-drawing-path instead of separate calls to begin-drawing-path and end-drawing-path. See also: line-end, with-line-end, line-join, with-line-join, end-drawing-path, and with-drawing-path.


bitmap-stream

Generic Function, cg package

Arguments: drawable

Returns the bitmap-stream most recently used by a drawable, or nil if none has been used. This function is not setf'able; the bitmap-stream is created automatically when the use-bitmap-stream property is turned on. Setting use-bitmap-stream to nil disassociates any bitmap-stream from a drawable, although this function will still return the now-unused bitmap-stream.

Thus, if use-bitmap-stream has been turned on and then off, then the leftover bitmap-stream will still be returned. Therefore, an application should not assume that a drawable is currently using a bitmap stream simply because bitmap-stream returns true. Call use-bitmap-stream instead to determine if one is currently being used.


bits-per-pixel

Generic Function, cg package

Arguments: object

Returns the number of bits that are used to represent each pixel of a pixmap or a window. Also known as the depth, the value may be 1, 4, 8, 16, 24, or 32. Depths of 16 bits or greater are known as "true color" because each pixel denotes a color value directly. (Sometimes 16 bits is referred to as "high color" rather than true color because only five bits are available for each of the red, green, and blue color components.) With depths of 8 and less, there are not enough bits to represent a color directly, so each pixel instead denotes an index into a table of colors. For a pixmap, this table is specified by the colors attribute. For a window, the table is specified by assigning a palette to the window, though a depth of 8 (for 256 colors) is generally the only one where the default system colors do not suffice.

Methods exist on pixmap, texture, basic-pane, and screen, though in Windows a single depth is used for the screen and all windows, according to the user's current Control Panel display setting. The depth of a pixmap does not need to match the depth of a window in which it is drawn, though the colors may not be correct when drawn in a window of a lower depth than the pixmap.


blink-off-milliseconds

Generic Function, cg package

Arguments: lamp

Returns or sets (with setf) the number of milliseconds the argument lamp will stay off when it is blinking (as it does when its value is :blinking).

See the description of the lamp control.


blink-on-milliseconds

Generic Function, cg package

Arguments: lamp

Returns or sets (with setf) the number of milliseconds the argument lamp will stay on when it is blinking (as it does when its value is :blinking).

See the description of the lamp control.


body-background-color

Generic Function, cg package

Arguments: chart-or-plot

Returns the value of the body-background-color property of a chart-or-plot. The value may be set at creation time by passing the :body-background-color initarg, or any time later by calling (setf body-background-color).

The background color for the body of a chart-or-plot inside the axes and labels. (The usual background-color property of the widget is used only for the part of the widget outside this area.)

The value is either an RGB object (see make-rgb), or nil to use the widget's default-background-color, or t to use the parent window's background-color. The default value is the value of white.

See chart-widget and also cg-chart-widget.html.


body-background-color-one

Generic Function, cg package

Arguments: grid-widget

Returns (or sets with setf) the background-color-one of the grid-row-section whose name is :body, if there is a row-section named :body in grid-widget (a grid-widget), or else returns nil. See background-color-one for more information.

This function is mainly for use when creating a grid-widget on a form window and modifying its properties (like this one) interactively in the inspector (see cg-grid-widget-simplified-tutorial.html). But it can be called programmatically at run time as well.


body-background-color-two

Generic Function, cg package

Arguments: grid-widget

Returns (or sets with setf) the background-color-two of the grid-row-section whose name is :body, if there is a row-section named :body in grid-widget (a grid-widget), or else returns nil. See background-color-two for more information.

This function is mainly for use when creating a grid-widget on a form window and modifying its properties (like this one) interactively in the inspector (see cg-grid-widget-simplified-tutorial.html). But it can be called programmatically at run time as well.


body-border-color

Generic Function, cg package

Arguments: chart-or-plot

Returns the value of the body-border-color property of a chart-or-plot. The value may be set at creation time by passing the :body-border-color initarg, or any time later by calling (setf body-border-color).

The color that is used to draw the border lines around the body of a chart-or-plot, inside the labels. The value should be either an RGB object (see make-rgb) or nil to default to the system-edge-shadow-color. The default value is nil.

Any side of the chart body that has an axis will use the axis-color of that chart-axis instead of this color, because the axis stem serves as that part of the chart body border.

See chart-widget and also .


body-border-width

Generic Function, cg package

Arguments: chart-or-plot

Returns the value of the body-border-width property of a chart-or-plot. The value may be set at creation time by passing the :body-border-width initarg, or any time later by calling (setf body-border-width).

The thickness in pixels of the border around the body of a chart-or-plot, inside the labels. The value should be a non-negative integer. Zero means no border is drawn. The default value is 3.

Any side of the chart body that has an axis will use the axis-width of that chart-axis instead of this value, because the axis stem serves as that part of the chart body border.

See chart-widget and also cg-chart-widget.html.


body-column-count

Generic Function, cg package

Arguments: grid-widget

Returns the number of columns that are in the grid-column-section whose name is :body, if there is such a section in the column-sections of grid-widget, and otherwise returns 0.

The setf of this function can be called (including at run time) to add or remove columns to that section. If a section named :body does not yet exist, then it is created, placing it just after the section named :header if there is one, or else at the front of all column sections.

See the more general function subsection-count (which this function calls) for more information. See also grid-widget.

This function is mainly for use when creating a grid-widget on a form window and modifying its properties (like this one) interactively in the inspector (see cg-grid-widget-simplified-tutorial.html). But it can be called programmatically at run time as well.


body-column-defaults

Generic Function, cg package

Arguments: grid-widget

Returns an object that specifies default property values for columns that are in a grid-column-section named :body, if there is such a section in the column-sections of grid-widget (which should be a grid-widget), and otherwise returns nil. See the general function subsection-defaults (which this function calls) for more information.

This function is mainly for use when creating a grid-widget on a form window and modifying its properties (like this one) interactively in the inspector (see cg-grid-widget-simplified-tutorial.html). But it can be called programmatically at run time as well.

Typically in the inspector you would go to this object from the grid-widget, and then specify some of the properties for most or all of the main body section of the grid-widget.

There is also footer-column-defaults (which links back to this page saying replace :body with :footer). There is no header-column-defaults as headers normally have only a single subsection.


body-columns

Generic Function, cg package

Arguments: grid-widget

Returns the list of grid-column objects that are in a grid-column-section named :body, if there is such a section in the column-sections of grid-widget, and otherwise returns nil. The more general function that can be called on any grid-section is subsections.

This function is mainly for use when creating a grid-widget on a form window and modifying its properties (like this one) interactively in the inspector (see cg-grid-widget-simplified-tutorial.html). But it can be called programmatically at run time as well.

A grid-widget that is placed onto a form window will initially have main column and row sections that are named :body, along with header sections that are named :header. When creating a grid-widget programmatically instead, you might want to use those names in custom code as well in order to use convenience functions like this one.

The setf of this function could be called to change the set of columns in the body column section, where any added columns will have properties from the body-column-defaults of grid-widget.


body-gradient-blend

Generic Function, cg package

Arguments: chart-or-plot

This property has an effect only on the Windows platform.

This property of chart-widget and plot-widget determines the value that *color-gradient-blend* will have while drawing the background area of the chart or plot. See *color-gradient-blend* for an explanation of its effect and the valid values.

The value can be set at creation time by passing the :body-gradient-blend initarg to make-instance, or any time later by calling (setf body-gradient-blend).


body-gradient-direction

Generic Function, cg package

Arguments: chart-or-plot

This property has an effect only on the Windows platform.

This property of chart-widget and plot-widget determines the value that *color-gradient-direction* will have while drawing the background area of the chart or plot. See *color-gradient-direction* for an explanation of its effect and the valid values.

The value can be set at creation time by passing the :body-gradient-direction initarg to make-instance, or any time later by calling (setf body-gradient-direction).


body-gradient-filling

Generic Function, cg package

Arguments: chart-or-plot

This property has an effect only on the Windows platform.

This property of chart-widget and plot-widget determines the value that *color-gradient-filling* will have while drawing the background area of the chart or plot. See *color-gradient-filling* for an explanation of its effect.

The value can be set at creation time by passing the :body-gradient-filling initarg to make-instance, or any time later by calling (setf body-gradient-filling).

To enable gradient filling in chart icons or bars, use icon-gradient-filling or bar-gradient-filling instead.


body-gradient-intensity

Generic Function, cg package

Arguments: chart-or-plot

This property has an effect only on the Windows platform.

This property of chart-widget and plot-widget determines the value that *color-gradient-filling* will have while drawing the background area of the chart or plot. See *color-gradient-filling* for an explanation of its effect and the valid values.

The value can be set at creation time by passing the :body-gradient-intensity initarg to make-instance, or any time later by calling (setf body-gradient-intensity).


body-left-indentation

Generic Function, cg package

Arguments: text-edit-pane

Returns the current indentation of the lefthand side of a paragraph of text in a text-edit-pane, or the indentation indicated by the corresponding lower-left slider of a rich-edit-ruler.

This generic function may be called either on a text-edit-pane (typically a rich-edit-pane) or on a rich-edit-ruler. The methods behave somewhat differently: for a text-edit-pane, body-left-indentation is relative to top-left-indentation to match the rich text specification and the Microsoft rich edit control; for a rich-edit-ruler, top-left-indentation is instead relative to body-left-indentation to match the intuitive practice of moving the overall indentation of one or more paragraphs without changing the relative indentation of the first line of each paragraph.

The text-edit-pane method returns the left indentation of the body of the paragraph that contains the text-edit-pane's text cursor (or the first paragraph partly or wholly contained in the selected text, if any). The body is considered to be all lines of the paragraph except the first. This value is measured in points, and is measured rightward from the text-edit-pane's top-left-indentation, which in turn is measured rightward from the interior left of the text-edit-pane. A point is one seventy-second of an inch. Therefore, if a paragraph's body is indented by one inch and its first line is indented by a further inch, the top-left-indentation would be 144 and the body-left-indentation would be -72. This is the way that the rich-edit control was designed in the operating system, and reflects the rich text specification and the values that appear in the rich text string that might be read from the text-edit-pane. For a more intuitive style of measurement, it may be preferable to use the indentation of an associated rich-edit-ruler instead.

The setf method for text-edit-pane sets the indentation of the body of the paragraph that contains the text cursor (or all paragraphs that are partly or wholly selected, if any). If there is a rich-edit-ruler associated with the text-edit-pane (see the function ruler), then the rich-edit-ruler's indentation will be automatically modified to match.

The rich-edit-ruler method returns the position of the slider at the lower left of the ruler, measured in points from the leftmost position. This is not relative to the position of the upper left slider, which is normally used to control the top-left-indentation of a text-edit-pane.

The setf method for rich-edit-ruler moves the lower-left slider of the ruler to the specified position. Since the top-left-indentation of a rich-edit-ruler is relative to the body-left-indentation, the upper-left slider will also move by the same amount. Each slider will be independently constrained at position 0 (the leftmost position) if an attempt is made to move it to a negative position. If there is a text-edit-pane associated with the ruler (see the function rich-edit), then the paragraph in the text-edit-pane that contains the text cursor (or all paragraphs that are partly or wholly contained in the selected text, if any) will be automatically modified to match.

To apply this function to a rich-edit control, first apply window to the control to obtain a rich-edit-pane to pass to this function.

To read or modify multiple paragraph attributes of a text-edit-pane at once, see get-paragraph-format or set-paragraph-format. See also right-indentation.

See cg-rich-text.html for information on rich text editing in Common Graphics.


body-row-count

Generic Function, cg package

Arguments: grid-widget

Returns the number of rows that are in the grid-row-section whose name is :body, if there is such a section in the row-sections of grid-widget, and otherwise returns 0.

The setf of this function can be called (including at run time) to add or remove rows to that section. If a section named :body does not yet exist, then it is created, placing it just after the section named :header if there is one, or else at the front of all row sections.

See the more general function subsection-count (which this function calls) for more information. See also grid-widget.

This function is mainly for use when creating a grid-widget on a form window and modifying its properties (like this one) interactively in the inspector (see cg-grid-widget-simplified-tutorial.html). But it can be called programmatically at run time as well.


body-row-defaults

Generic Function, cg package

Arguments: grid-widget

Returns an object that specifies default property values for rows that are in a grid-row-section named :body, if there is such a section in the row-sections of grid-widget (which should be a grid-widget), and otherwise returns nil. See the general function subsection-defaults (which this function calls) for more information.

This function is mainly for use when creating a grid-widget on a form window and modifying its properties (like this one) interactively in the inspector (see cg-grid-widget-simplified-tutorial.html). But it can be called programmatically at run time as well.

Typically in the inspector you would go to this object from the grid-widget, and then specify some of the properties for most or all of the main body section of the grid-widget.

There is also footer-row-defaults (which links back to this page saying replace :body with :footer). There is no header-row-defaults as headers normally have only a single subsection.


body-row-height

Generic Function, cg package

Arguments: class-grid

Returns the initial section-size of the grid-rows in the body of a class-grid. The value may be set with the body-row-height initarg or by calling (setf body-row-height). Setting the value will changed the section-size of every body row to that size.


body-rows

Generic Function, cg package

Arguments: grid-widget

Returns the list of grid-row objects that are in a grid-row-section named :body, if there is such a section in the row-sections of grid-widget, and otherwise returns nil. The more general function that can be called on any grid-section is subsections.

This function is mainly for use when creating a grid-widget on a form window and modifying its properties (like this one) interactively in the inspector (see cg-grid-widget-simplified-tutorial.html). But it can be called programmatically at run time as well.

A grid-widget that is placed onto a form window will initially have main column and row sections that are named :body, along with header sections that are named :header. When creating a grid-widget programmatically instead, you might want to use those names in custom code as well in order to use convenience functions like this one.

The setf of this function could be called to change the set of rows in the body row section, where any added rows will have properties from the body-row-defaults of grid-widget.


bold

Generic Function, cg package

Arguments: text-edit-pane

The function returns t if all of the selected range of text-edit-pane is bold, nil if it is all non-bold, and :some if there is a mix.

The setf function turns boldness on or off in the selected range of text-edit-pane. value is either nil to turn it off or true to turn it on.

text-edit-pane must be an instance of a text-edit-pane (which is a superclass of rich-edit-pane). It cannot be a text-edit-window or a rich-edit control (apply window to a rich-edit control to get a value suitable as an argument to this function).

See cg-rich-text.html for information on rich text editing in Common Graphics.


bold-text

Generic Function, cg package

Arguments: cell-style

A boolean property of a cell-style of a calendar widget. When true, the text in the calendar cells for that cell-style will be drawn in bold, and otherwise they will not (unless the font property of the calendar widget is bold itself).

See also the calendar class and the function ask-user-for-date.


border

Generic Function, cg package

Arguments: window-or-widget

Returns the style of the window-or-widget's border. Various border styles are listed below. Only some styles are appropriate for a specific object.

The border property may not be changed on an existing window or widget, and must instead be specified with the inspector when designing a window or widget (using a form window) or with the :border initarg of make-window or (for a widget) make-instance. (It can be changed using the inspector when designing a form window but not for a running window or widget, either in the IDE or in an application.)

Here are the possible values and their effects:

For group-box widgets the border can have the following special properties:


border-color

Generic Function, cg package

Arguments: grid-object

Returns the color that will be used to draw border lines in a grid-widget, grid-section, scrolling-static-text, chart-legend, or lamp. The value may be set at creation time by passing the border-color initarg, or any time later by calling (setf border-color).

Border-color for a grid-widget or grid section

Specifies the color in which to draw a border line along the right side of a grid-column or grid-column-section, or along the bottom of a grid-row or grid-row-section, or around an entire grid-widget.

The value may be either an RGB color object (as returned by make-rgb or ask-user-for-color), or a symbol whose global value is an RGB object, or nil to use a default color. The value may also be t to to use the system-edge-shadow-color. The default is t for a grid-widget and nil for the others.

When nil, effective-border-color will find the default color to use (except for a grid-widget, where nil will use black).

Border-color in a scrolling-static-text

The value may be nil to draw no border at all, or an RGB color object (see make-rgb) to draw a border in that color, or t to draw a border in the system-edge-shadow-color. The default is nil. See also draw-focus.

Border-color in a chart-legend of a chart-widget

Returns the value of the border-color property of a chart-legend. The value may be set at creation time by passing the border-color initarg, or any time later by calling (setf border-color).

The color that is used to draw the rectangular border around the chart-legend of a chart-widget. The value should be an RGB object (see make-rgb). The default value is the value of gray.

This property is used only when the draw-legend and draw-legend-border properties of the chart-legend are both true.

Border-color in a lamp widget

Specifies the color of the lines that are drawn for the perimeter of each lamp image, as opposed to the on-color and off-color that are used to fill the image. (A border is never drawn around the entire widget.) The default is the value of the constant black.


border-dashing

Generic Function, cg package

Arguments: grid-section-any

Returns the border-dashing property of its argument. That property specifies the style of dashed or solid line that will be used for a grid-row or grid-column. The possible values are the same as the possible values of line-dashing.


border-margin

Generic Function, cg package

Arguments: calendar-widget

The number of blank pixels between a calendar widget's external border and the content inside.

Several pixels are suitable when show-focus-box is true, to avoid the focus box being adjacent to the calendar contents. But if is nil then this property could be zero to minimize the space that the widget occupies.

See also the calendar class and the function ask-user-for-date.


border-width

Generic Function, cg package

Arguments: grid-object

Returns the width in pixels, if one has been specified, with which to draw a border along the right side of a grid-column or grid-column-section, or along the bottom of a grid-row or grid-row-section, or around an entire grid-widget. The setf of this function may be called to change the width, at which time the grid will be drawn as needed to display the new border width.

The value may be either a non-negative integer or nil. The initial value is nil. When nil, effective-border-width will find a width to use in some other way. Zero means to draw no border at all (though cell-3d-border may still be used to draw a separate 3d border).

An exception to the above rule is that if the object is a grid-widget then nil is not a valid value, the initial value is 3, and effective-border-width is not called.


bottom

Generic Function, cg package

Arguments: box

Returns the coefficient of the bottom of box.


bottom-attachment

Generic Function, cg package

Arguments: standard-object

Returns or sets with setf the value of the bottom-attachment property of the argument. This property determines which edge of the parent window the bottom edge the object will follow whenever the parent window gets resized. See also top-attachment, left-attachment, and right-attachment.

The possible values and their effects are:

A control that drops a list of choices when clicked (namely a combo-box or dropping-outline control) always has the same height when not showing its dropping list, and so bottom-attachment for these controls applies to the bottom of the dropped list of choices instead. To keep the dropping list the same height as the user resizes the parent window, bottom-attachment should be the same as the top-attachment. (When both attachments are :scale, a control normally resizes proportionally as its parent window is resized; a dropping list is an exception since it is typically more desirable for the list to continue to show the same number of items than it is to prevent it from overlapping other controls.)

See also top-attachment, left-attachment, right-attachment, track-limits and resize-window.


bottom-margin

Generic Function, cg package

Arguments: graphical-stream &optional (stream-units-p t)

Returns the current bottom margin of a graphical-stream, measured from the top edge of the stream. The bottom-margin is initially the page-height of the stream, except as noted below. (setf bottom-margin) may be called to set the margin at any time.

If stream-units-p is true, as it is by default, then the margin is measured in pixels. If nil, it is measured in text line heights (see line-height.

Margin attributes are provided primarily to allow an application to keep a drawing within arbitrary margins by drawing everything within the coordinates returned by left-margin, top-margin, right-margin, and bottom-margin, Common Graphics also uses them in a few special ways, though, as described below.

When drawing on a printer stream, typically an application should check whether the next thing that it is about to draw would extend past the bottom-margin. If so, then it should call new-page to tell the printer to move to a new sheet of paper, and then proceed to draw on the new page. The call to new-page will set the current-position-x of the stream to its left-margin and the current-position-y of the stream to its top-margin, so that text output will continue from the top of the new page. For other drawing functions, the application should adjust the coordinates at which it is drawing, generally by subtracting the page-length of the stream. The page-length is equal to the stream's top-margin subtracted from its bottom-margin.

A printer stream's coordinate system has position (0, 0) at the printer-physical-offset of the printer. To allow an application to avoid dealing with this arbitrary offset, Common Graphics sets the margins of a printer stream to the distance from the physical offset to the margins selected by the user in the print job dialog or page setup dialog. This allows the application to maintain the requested paper margins by simply drawing everything within the four margins that were set up automatically. See *default-printer-left-margin* for more information.


box

Generic Function, cg package

Arguments: object

Returns a box object that specifies the exterior of the argument object with respect to its parent. The object may be a dialog-item, or window (though box simply calls exterior when passed a non-widget window). (setf box) may be called to resize the object.

When passed a combo-box or dropping-outline dialog-item (or the dialog-item's window), the returned box includes the height of the dropping pane of the widget. Similarly, when calling (setf box), the height should specify the height of the widget with its dropping pane; this determines how far the dropping pane can extend downward. (The undropped widget is maintained at a standard height.) To instead find the box that does not include the dropping pane, use (exterior (window dialog-item)) (see exterior and window).

Beginning in version 7.0, the box method specializing on hotspot has become the new generic function hotspot-region, though the box method for hotspots and its associated :box initarg still exist for compatibility.


box-bottom

Function, cg package

Arguments: box

Returns the bottom of box. This function is setf'able. Thus:

;; We create a box object and then modify the left, top, and right
;; components using SETF and the SETF function (note the arguments
;; to the SETF function are NEW-VALUE BOX).
;; These ways work for each component.
;;
cg-user(26): (setq b1 (make-box 10 20 30 40))
#<box 10 20 30 40>
cg-user(27): (list (box-left b1) (box-top b1) (box-right b1) (box-bottom b1))
(10 20 30 40)
cg-user(28): (setf (box-left b1) 11)
11
cg-user(29): (setf (box-top b1) 21)
21
cg-user(30): (apply #'(setf box-right) (list 31 b1))
31
cg-user(31): (list (box-left b1) (box-top b1) (box-right b1) (box-bottom b1))
(11 21 31 40)
cg-user(32): 

See the description of the box class for general information on boxes.


box-bottom-center

Function, cg package

Arguments: box &optional position-to-return

Returns the position that is the center of the bottom of box rounding down if necessary. If position-to-return is supplied and non-nil, it must be a position object (see make-position). In that case, position-to-return is returned, after being modified to be the right center of box. If position-to-return is nil, a new position object is returned.

See the description of the box class for general information on boxes.


box-bottom-left

Function, cg package

Arguments: box &optional position-to-return

Returns the position that is the bottom left corner of box. If position-to-return is supplied and non-nil, it must be a position object (see make-position). In that case, position-to-return is returned, after being modified to be the right center of box. If position-to-return is nil, a new position object is returned.

See the description of the box class for general information on boxes.


box-bottom-right

Function, cg package

Arguments: box &optional position-to-return

Returns the position that is the bottom right corner of box. If position-to-return is supplied and non-nil, it must be a position object (see make-position). In that case, position-to-return is returned, after being modified to be the right center of box. If position-to-return is NIL, a new position object is returned.

See the description of the box class for general information on boxes.


box-center

Function, cg package

Arguments: box &optional position-to-return

Returns the position that is the center of box, rounding down where necessary. If position-to-return is supplied and non-nil, it must be a position object (see make-position). In that case, position-to-return is returned, after being modified to be the right center of box. If position-to-return is nil, a new position object is returned.

See the description of the box class for general information on boxes.


box-center-x

function, cg package

Arguments: box

Returns an integer for the horizontal middle of the specified box. The argument should be a box; see make-box.


box-center-y

function, cg package

Arguments: box

Returns an integer for the vertical middle of the specified box. The argument should be a box; see make-box.


box-height

Function, cg package

Arguments: box

Returns the height of box.

See the description of the box class for general information on boxes.


box-intersect

Function, cg package

Arguments: box1 box2 &optional box-to-return

Returns the box which is the intersection of the arguments, or nil if they do not intersect. If box-to-return is specified and non-nil, it must be a box object (see make-box. If that case, box-to-return will be modified to be the intersection, if box-intersect returns non-nil. (This will save space by avoiding the creation of a new box object.) If box-to-return is unspecified or specified nil, a new box is created if the arguments intersect.

Boxes which touch just on their edges or at the vertices are not considered to intersect. Thus,

(make-box 10 10 20 20)

does not intersect

(make-box 20 20 30 30)

but does intersect

(make-box 19 19 30 30)

See the description of the box class for general information on boxes.


box-intersect-p

Function, cg package

Arguments: box1 box2

Returns true if the argument boxes intersect and returns nil if they do not intersect. Boxes which touch just on their edges or at the vertices are not considered to intersect. Thus,

(make-box 10 10 20 20)

does not intersect

(make-box 20 20 30 30)

but does intersect

(make-box 19 19 30 30)

See the description of the box class for general information on boxes.


box-left

Function, cg package

Arguments: box

Returns the coordinate of the left edge of box. This function is setf'able. Thus:

;; We create a box object and then modify the left, top, and right
;; components using SETF and the SETF function (note the arguments
;; to the SETF function are NEW-VALUE BOX).
;; These ways work for each component.
;;
cg-user(26): (setq b1 (make-box 10 20 30 40))
#<box 10 20 30 40>
cg-user(27): (list (box-left b1) (box-top b1) (box-right b1) (box-bottom b1))
(10 20 30 40)
cg-user(28): (setf (box-left b1) 11)
11
cg-user(29): (setf (box-top b1) 21)
21
cg-user(30): (apply #'(setf box-right) (list 31 b1))
31
cg-user(31): (list (box-left b1) (box-top b1) (box-right b1) (box-bottom b1))
(11 21 31 40)
cg-user(32): 

See the description of the box class for general information on boxes.


box-left-center

Function, cg package

Arguments: box &optional position-to-return

Returns the position which is the center of the left edge of box, rounding down if necessary. If position-to-return is supplied and non-nil, it must be a position object (see make-position). In that case, position-to-return is returned, after being modified to be the right center of box. If position-to-return is nil, a new position object is returned.

See the description of the box class for general information on boxes.


box-move

Function, cg package

Arguments: box offset

Returns a new box object created from box and offset as follows:

(make-box (+ (box-left box) (position-x offset))
          (+ (box-top box) (position-y offset))
          (+ (box-right box) (position-x offset))
          (+ (box-bottom box) (position-y offset)))  

See make-box and the description of the box class for general information on boxes. See also nbox-move, which modifies its box argument rather than creating a new box object.


box-right

Function, cg package

Arguments: box

Returns the coordinate of the right edge of box. This function is setf'able. Thus:

;; We create a box object and then modify the left, top, and right
;; components using SETF and the SETF function (note the arguments
;; to the SETF function are NEW-VALUE BOX).
;; These ways work for each component.
;;
cg-user(26): (setq b1 (make-box 10 20 30 40))
#<box 10 20 30 40>
cg-user(27): (list (box-left b1) (box-top b1) (box-right b1) (box-bottom b1))
(10 20 30 40)
cg-user(28): (setf (box-left b1) 11)
11
cg-user(29): (setf (box-top b1) 21)
21
cg-user(30): (apply #'(setf box-right) (list 31 b1))
31
cg-user(31): (list (box-left b1) (box-top b1) (box-right b1) (box-bottom b1))
(11 21 31 40)
cg-user(32): 

See the description of the box class for general information on boxes.


box-right-center

Function, cg package

Arguments: box &optional position-to-return

Returns the position of the right center of box, rounding down if necessary. If position-to-return is supplied and non-nil, it must be a position object (see make-position). In that case, position-to-return is returned, after being modified to be the right center of box. If position-to-return is nil, a new position object is returned.

See the description of the box class for general information on boxes.


box-to-drag

Generic Function, cg package

Arguments: dialog-item

Should return a box indicating the section of the control's image that should be dragged along with the mouse cursor during a drag-and-drop gesture (see drag-and-drop). The box should be relative to the upper left corner of the scrollable contents of the control.

Methods are supplied for most controls to return the area occupied by the currently selected value of the control.

This image is used only if

(drag-images (configuration *system*))

has been set to true. It is nil by default. (See drag-images, configuration, and *system*.)


box-top

Function, cg package

Arguments: box

Returns the coordinate of the top of box. This function is setf'able. Thus:

;; We create a box object and then modify the left, top, and right
;; components using SETF and the SETF function (note the arguments
;; to the SETF function are NEW-VALUE BOX).
;; These ways work for each component.
;;
cg-user(26): (setq b1 (make-box 10 20 30 40))
#<box 10 20 30 40>
cg-user(27): (list (box-left b1) (box-top b1) (box-right b1) (box-bottom b1))
(10 20 30 40)
cg-user(28): (setf (box-left b1) 11)
11
cg-user(29): (setf (box-top b1) 21)
21
cg-user(30): (apply #'(setf box-right) (list 31 b1))
31
cg-user(31): (list (box-left b1) (box-top b1) (box-right b1) (box-bottom b1))
(11 21 31 40)
cg-user(32): 

See the description of the box class for general information on boxes.


box-top-center

Function, cg package

Arguments: box &optional position-to-return

Returns the position that is the center of the top of box, rounding down if necessary. If position-to-return is supplied and non-nil, it must be a position object (see make-position). In that case, position-to-return is returned, after being modified to be the right center of box. If position-to-return is nil, a new position object is returned.

See the description of the box class for general information on boxes.


box-top-left

Function, cg package

Arguments: box &optional position-to-return

Returns the position that is the top left corner of box. If position-to-return is supplied and non-nil, it must be a position object (see make-position). In that case, position-to-return is returned, after being modified to be the right center of box. If position-to-return is nil, a new position object is returned.

See the description of the box class for general information on boxes.


box-top-right

Function, cg package

Arguments: box &optional position-to-return

Returns the position that is the top right corner of box. If position-to-return is supplied and non-nil, it must be a position object (see make-position). In that case, position-to-return is returned, after being modified to be the right center of box. If position-to-return is nil, a new position object is returned.

See the description of the box class for general information on boxes.


box-union

Function, cg package

Arguments: box1 &rest boxes

Returns a box that is the union of box1 and the other argument boxes. The union of several boxes is the smallest box that contains them all.

See the description of the box class for general information on boxes.


box-width

Function, cg package

Arguments: box

Returns the width of box.

See the description of the box class for general information on boxes.


boxp

Generic Function, cg package

Arguments: object

Returns t if the argument is a box object and returns nil otherwise.

See the description of the make-box for more information on boxes.

Warning about positions created by the with-boxes and with-positions-and-boxes

boxp should not be called on objects created by the macros with-boxes and with-positions-and-boxes. The return value of those functions is undefined for objects created by the macros because type information for such objects is sacrificed to achieve the non-consing efficiency of stack allocation.


box=

Function, cg package

Arguments: box1 box2

Returns true if box1 and box2 are boxes with the same location and dimensions (they need not be the same Lisp objects). Returns nil if box1 and box2 are different.

See the description of the box class for general information on boxes.


brief-comtab

Generic Function, cg package

This function has been removed in the 7.0 release. In earlier releases, it returned the brief comtab that was used internally in the IDE editor. The IDE configuration option ide:editor-mode (with its widget on the Editor tab of the Options) is the exported way to select which comtab the editor uses. The code called by these comtabs exists mostly in the IDE only, and so these comtabs were not useful for applications.


bring-window-to-front

Generic Function, cg package

Arguments: window &key recurse

Brings window in front of all of its sibling windows, if it is not already in front. If recurse is true, then the same thing is done to each of window's ancestor windows, which guarantees that window will not remain behind any window in the whole window hierarchy. See also select-window, which brings a window to the front and selects it.

If you are running a multi-threaded Common Graphics application in Windows desktop mode, see set-foreground-window, because this function (and select-window) may not reliably move a top-level window in front of windows that were created by other threads.


buddy-side

Generic Function, cg package

Arguments: up-down-control

Returns the side of a buddy-widget to which the up-down-control is attached. See up-down-control.

The buddy-side property may not be changed on an existing control, and must instead be specified with the inspector when designing a control (using a form) or with the :buddy-side initarg of make-instance. (It can be changed using the inspector when designing a form but not for a running control, either in the IDE or in an application.)

buddy-side is a property of the up-down-control class.


buddy-widget

Generic Function, cg package

Arguments: up-down-control

Returns the name of the control to which the argument up-down-control, which must be an up-down-control, is attached. That control is called the buddy-widget. A typical buddy widget is an editable-text control with a numeric value. The value can be increased or decreased with the up-down control (as well as typing directly into the text control).

See also the generic function up-down-control.

When designing a form with the IDE, a buddy-widget is connected to an up-down control by clicking on the up-down-control, dragging it over the desired buddy, and dropping it over either the left or the right side of the buddy. A buddy control may be programmatically connected by passing the name of the desired editable-text control as the value of the :buddy-widget initarg when creating the up-down-control, and by passing the name of the up-down-control as the value of the :up-down-control initarg when creating the editable-text control.

Here are the possible values and their effects:

buddy-widget is a property of the up-down-control class.


build-number

Generic Function, cg package

Arguments: project-or-app

Returns an integer that indicates how many times the standalone application for a project has been built. This information could be presented in an About dialog, for example, to distinguish between builds.

This project property is automatically incremented each time the File | Build Project Distribution command is used to generate the standalone app, and the setf of this function could be used to set the value arbitrarily (though it should always be a non-negative integer). The build-number of a new project will be zero, and the first build will be build number 1.

In the standalone application (as well as in the IDE), build-number is also a property of the app object, where it can be retrieved with the expression (build-number (app *system*)), since the project itself is not present in the generated app.

If you build projects programmatically by calling build-project, then you could avoid incrementing the build-number of the project by passing the increment-build-number argument as nil. That would avoid modifying the project and making the IDE inclined to save it.


bury-component

Generic Function, cg package

Arguments: widget

Moves widget to the bottom of the occlusion stack, so that it will appear behind any overlapping controls. Further, widget is placed last in the tab order for the dialog.


bury-window

Function, cg package

Arguments: window

Moves window to the bottom of the occlusion stack, so that it will appear behind any overlapping sibling windows.


button-3d-border

Generic Function, cg package

Arguments: multi-picture-button

Returns (or sets with setf) the value of the button-3d-border property of a multi-picture-button. This value determines what kind of border with a three-dimensional appearance (if any) will be drawn around each button of the widget. Here are the valid values:

The 3d border is independent of the button-black-border, which is drawn around the 3d border if both are specified. The borders are drawn around the padding of each button but not around the spacing between the buttons.


button-black-border

Generic Function, cg package

Arguments: multi-picture-button

Returns (or sets with setf) the value of the button-black-border property of multi-picture-button. This value determines whether a thin black border is drawn around each button of the control.

The black border is independent of the button-3d-border, which is drawn inside the black border if both are specified. The borders are drawn around the padding of each button but not around the spacing between the buttons.

button-black-border is a property of the multi-picture-button class.


button-fills-cell

Generic Function, cg package

Arguments: static-text-and-button-column-mixin

Returns (or sets with setf) whether the buttons in the specified grid-column fill their cells or are small buttons in the lower right corners of the cells.

If the value of this static-text-and-button-column-mixin property is true, then the button in each widget-row-mixin cell of this column will fill the entire cell (within the cell's cell-vertical-padding and cell-horizontal-padding), and the cell's text will be drawn inside the button. If nil, then the button will be small and located in the lower right corner, with the text printed to the left of the button.

Compatibility notes

The default value is nil for backward compatibility, though true may be a more aesthetically pleasing choice, and may fit more text into the cell. The name static-text-and-button-column-mixin to which this property applies is not quite accurate when this option is turned on, but has been kept for compatibility as well.

See the grid-widget class for an overview of writing grid-widget code.


button-function

Generic Function, cg package

Arguments: static-text-and-button-column-mixin-instance

Returns the name of a function that will be run when the small button in a grid-column of class static-text-and-button-column-mixin (in a grid-widget) is pressed. A button-function may also be nil instead of a function, in which case the button will do nothing. The default is nil.

A button-function should take six arguments: (1) the grid-widget, (2) the data-object of the grid-row that the clicked cell is in, (3) the grid-row, (4) the grid-column, (5) the row number, and (6) the column number. In releases before 8.0, the function took four arguments (the first four listed) and four arguments will still work but code should be changed to use six arguments. Defining the arguments as optional will allow correct code in both 8.0 and earlier releases.


button-info-p

Generic Function, cg package

Arguments: object

Returns true if the argument is an instance of the button-info class and returns nil otherwise.


button-match

Macro, cg package

Arguments: button-state button-form

Compares the button-state to the buttons described in button-form. button-form is recursively defined as follows:

simple-button-form | 
(only simple-button-form) |
(not button-form) |
(or button-form*) | 
(and button-form*) | 
NONE | 
nil | 
UP

Where simple-button-form can be any constant with an integer value. Examples of button-forms are:

meta-key 
(only shift-key)
(and (or shift-key meta-key) (not left-mouse-button))

button-p

Function, cg package

This function is no longer supported. typep instead.


button-return

Function, cg package

Arguments: button-widget new-value old-value

A function that can be used as the on-change event-handler for a button component when the only desired action of the button is to return from a modal dialog invocation, returning the button component itself from pop-up-modal-dialog.


button-style

Generic Function, cg package

Arguments: common-control

Returns the value of the button-style property of its argument. This property determines whether headers look like buttons (value t) or not (value nil).

The button-style property may not be changed on an existing control, and must instead be specified with the inspector when designing a control (using a form) or with the :button-style initarg of make-instance. (It can be changed using the inspector when designing a form but not for a running control, either in the IDE or in an application.)

button-style is a property of the header-control and tab-control classes.


cache-all-cell-values

Generic Function, cg package

Arguments: grid-widget

Caches the values for all cells of grid-widget that are not cached already. Also calls invalidate on grid-widget to cause it to be redrawn with possibly updated application values. This function should be called only on a grid-widget whose cache-cell-values property is true. See that property for more information.

To ensure that all cached values are up-to-date, call clear-cached-cell-values just before calling this function.

If reading cell values takes significant time, then calling this function may cause an initial delay as all cell values are read and cached, but may make scrolling faster by avoiding reading and caching values when they are first scrolled into view later. For a very large grid, the space to store all of the cached values may be significant.

Using this function can also prevent cell values from being read at unpredictable redisplay times, when it might not be safe. For example, if a read-cell-value method is reading from a remote database (this includes when the data-object of a grid row is a remote database object), then a redisplay at an unpredictable time could attempt to read its value while other code is already reading it. Calling this function at a known safe time will cache values so that they will not get read at redisplay time.


cache-cell-values

Generic Function, cg package

Arguments: grid-widget

Returns whether grid-widget (which must be a grid-widget) will cache cell values that it reads, to minimize the number of calls to application code that returns data to display. The value may be set at creation time by passing the cache-cell-values initarg, or any time later by calling (setf cache-cell-values). The default value is nil.

If nil, then application code is called every time a grid cell is drawn, to find the value to display in that cell. This involves calling read-cell-value methods or data-reader functions that are supplied by the application. If this code takes significant time, then it can slow down the drawing of a grid-widget. This may be especially noticeable during smooth scrolling. The application code can also be called many times when sort-grid is called.

If true, then a read-cell-value :around method will cache the value that is read for a cell the first time the cell is drawn, and then use the cached value any time the cell is redrawn thereafter. This continues until the application either calls clear-cached-cell-value for that cell, or calls clear-cached-cell-values to uncache the values for all cells of the grid-widget. To read and cache the values of all cells at once (rather than waiting until if and when they get displayed), call cache-all-cell-values.


cache-cursor

Function, cg package

Arguments: cursor

Stores cursor into a global list of stored cursors, so that it can later be found from its name by calling find-cursor. Similar to cache-pixmap for pixmaps. See also uncache-cursor.

All of the built-in mouse cursors are always cached, so this function is needed only when defining a custom mouse cursor, which is possible only in Windows desktop mode. See the section on mouse cursors in cg-pixmaps.html.


cache-pixmap

Generic Function, cg package

Arguments: pixmap

Stores pixmap internally so that it can later be retrieved by calling find-pixmap on its name.


calendar-date

Generic Function, cg package

Arguments: calendar-widget

Returns an integer (1 to 31) for the date of the universal time that is currently the value property of a calendar widget.

See also the cell-style class and the calendar class.


calendar-day

Generic Function, cg package

Arguments: calendar-widget

Returns an integer (0 to 6, where 0 means Monday) for the weekday of the universal time that is currently the value property of a calendar widget.

See also the cell-style class and the calendar class.


calendar-mode

Generic Function, cg package

Arguments: calendar-widget

The type of date range that a calendar widget is currently displaying. The value should be one of the keyword symbols :month, :year, :decade, or :century. The value may be set to switch the mode programmatically, though typically the user switches it interactively after the calendar is initially displayed in :month mode.

See also the cell-style class and the calendar class.


calendar-month

Generic Function, cg package

Arguments: calendar-widget

Returns an integer (1 to 12) for the month of the universal time that is currently the value property of a calendar widget.

See also the cell-style class and the calendar class.


calendar-title-font

Generic Function, cg package

Arguments: calendar-widget

The font to use for the title of a calendar widget. The value nil means to use the same font as the body, from the font property.

See also the calendar class and the function ask-user-for-date.


calendar-year

Generic Function, cg package

Arguments: calendar-widget

Returns an integer for the year of the universal time that is currently the value property of a calendar widget.

See also the cell-style class and the calendar class.


call-js

Function, cg package

Arguments: alist module &key reply-needed read-reply-from-string even-when-exiting

Calls a function in custom JavaScript code that's running in a web browser for a CG/JS application, after import-javascript-file was called at run time to load the JS file. The possibilities for this function are not described completely here, but this may be enough for making basic calls into JavaScript.

The alist argument will be described last, because its entry is long.

The module argument is the pathname-name of the JavaScript file that was loaded by calling import-javascript-file. This is used for cleanly separating the namespaces of multiple JavaScript files that might get imported and the namespace of the internal JS code of CG. It also fits well with the way that the JavaScript import function works.

If reply-needed is true, then call-js will not return until the JS function that was called returns, and the internal JS code of CG then sends a reply to lisp. call-js will then receive as a string whatever the JS function returned, and will return that string. If you would like to return a set of values, then your JS code could call encodeLispArgs (a CG function) on a JS array of values, and then lisp will receive a string that the lisp reader would read as a lisp list.

If read-reply-from-string is true, then call-js will call read-from-string inside an error handler on the string that was received from the web browser, and then return either the value that was read or nil if an errored was signaled. If your JavaScript code called encodeLispArgs on a JS vector to derive the string to return, then this should result in call-js returning a lisp list.

If even-when-exiting is true, then call-js will make the call even if lisp has begun the process of exiting. Otherwise it will not make the call because that might interfere with lisp exit, and so it will immediately return nil. In no case will it attempt the call if it is known that the web browser has disconnected, such as by the user closing the browser tab.

The main alist argument is an association list that contains entries for the name of the function that's being called and the arguments to pass to it. For example, this code snippet emulates how the CG function move-window tells the JS code to do the move:

  (call-js
   `((fun "moveWindow")
     (args ,(list (handle window)
                  (position-x position)(position-y position))))
   "one") ;; the pathname-name of the JS file that was imported

That calls a JavaScript function that looks like this:

function moveWindow (handle, x, y) {
  var frame = windows[handle];
  var fstyle = frame.style;
  fstyle.left = x + "px";
  fstyle.top = y + "px";
}

You generally should not call built-in CG functions like that one, because CG (in lisp) would not be aware of that and may get confused. But you can call your own JavaScript code in a similar way, and you could even import a file named "one.js" that exports its own function named moveWindow and call it as in that example.

CG internally uses that form of the alist argument for almost all of its calls, where the alist has a "fun" entry with the name of the JavaScript function to call, followed by an "args" entry with the arguments to pass. The alist keywords like "fun" and "args" are symbols, but the package of the symbols that you use does not matter because only their string names are passed to JS.

An alternate format for calling call-js uses individual named arguments in the association list instead of a single "args" argument. This is similar to passing keyword arguments in lisp. If the moveWindow example were written that way, then the lisp code might look like this, with argument names as alist keys:

  (call-js `((fun "moveWindow")
             (handle ,(handle window))
             (x ,(position-x position))
             (y ,(position-y position)))
           "one") ;; the pathname-name of the JS file

Then the JavaScript function would be called with a single JS object whose property names are those alist keys, and JS code can extract the individual values from that object by name:

function moveWindow (args) {
  var frame = windows[args.handle];
  var fstyle = frame.style;
  fstyle.left = args.x + "px";
  fstyle.top = args.y + "px";
}

Those examples show how CG passes a window to JavaScript by sending its handle, which in CG/JS is an integer. This is done because lisp objects would make no sense in JavaScript, of course. Then the JS code finds its HTML element for the window by using that integer as an index in a global "windows" vector that maps window handles to the HTML elements that serve as windows in the web browser. A JS vector works because the window handles are sequential positive integers beginning with 1, while zero is reserved for the screen. So windows[1] in the JavaScript code will return the first window that was created, while windows[0] will return the element that acts as the logical screen for the CG/JS app. (Or you could use the variable cgScreen, which holds the CG screen element.)

If you want your JS code to use windows that were created by CG, then you may need to do something like adding a layer of functions that accept a CG handle, then find the CG window element for the handle, and pass that to one of your existing functions. Something like this:

function doSomethingFromCG (cgWindowHandle) {
  doSomething(windows[cgWindowHandle]);
  }
function doSomething (htmlElement) {
  ... }

If you instead want to pass references to HTML elements that your JS code has created, then you could for example pass the HTML id attribute of the element instead of a CG window handle, and then find the HTML element itself in your JS code by calling document.getElementById as usual. Or use document.querySelector from scratch in your JS code.

One paradigm that may be useful is using an existing JS function that draws content to draw that content in a CG window. This would need to deal with the design where any regular CG window has an outer parent HTML element for the CG border and title bar, which has a child element for the interior of the window, and that child has a child that's a JS canvas for drawing on. CG stores the interior of a parent in an interior attribute, and the canvas of the interior element in a canvas attribute. So a custom JS function for drawing something in a CG window could begin like this to find the context for passing to JS drawing functions:

function drawMyDiagram (cgWindowHandle) {
  let canvas = windows[cgWindowHandle].interior.canvas;
  let ctx = canvas.getContext("2d");

Some types of lisp values get converted automatically as needed for passing to JavaScript. The symbol nil will be passed as the JavaScript value false, while t will be passed as true. Other symbols will be passed as their symbol name strings, with no package qualifier. Numbers will be passed as numbers. A CG rgb color object (as created with make-rgb) will be passed as a JS RGBA color string like "#64ffc8ff". Any non-empty lisp list will be passed as a JavaScript array, and elements of a list will be converted in a similar way (but only a single level down).

Another paradigm might involve calling existing JS code that creates its own HTML elements, but placing the top-level element into a CG window or onto the logical CG screen. That would allow mixing trees of custom JS elements with trees of CG windows, though it's less obvious what typical use cases may be.

As a final more complete example, here is code from a trivial sample project that demonstrates the two paradigms mentioned above. First, here is the JavaScript code, which exports a drawCheckerBoard function to draw a checker board in random colors inside a CG window, and a newElement function that creates a custom HTML element in a CG window or on the CG screen:

function drawCheckerBoard (handle) {
  let canvas = windows[handle].interior.canvas;
  let ctx = canvas.getContext("2d");
  let count = 8, size = 40, color, useFirstColor = true;
  let colorOne = randomColor(), colorTwo = randomColor();
  for (let x = 0; x < count; x++) {
    for (let y = 0; y < count; y++) {
      if (y > 0) useFirstColor = !useFirstColor;
      color = useFirstColor ? colorOne : colorTwo;
      ctx.fillStyle = color;
      ctx.fillRect(x * size, y * size, size, size);
    } } }
function newElement (handle, left, top, width, height) {
  let parent = windows[handle];
  parent = parent.interior || parent;
  let element = document.createElement("div");
  let previousElement = parent.currentElement;
  if (parent.currentElement) parent.removeChild(previousElement);
  parent.currentElement = element;
  let style = element.style;
  let borderColor = randomColor(), borderWidth = 4, padding = 8;
  let interiorDecrement = 2 * (borderWidth + padding);
  style.display = "block"; style.position = "absolute";
  style.padding = padding + "px"; style.borderRadius = "16px";
  style.background = "#bbddeecc";
  style.left = left + "px"; style.top = top + "px";
  style.width = width - interiorDecrement + "px";
  style.height = height - interiorDecrement + "px";
  style.border = borderWidth + "px solid " + borderColor;
  element.innerText = "This border color is " + borderColor + ".";
  element.fontSize = 14;
  style.fontSize = element.fontSize + "px";
  element.onmousedown = function () {
    this.fontSize += 1; // increase the font size when clicked
    this.style.fontSize = this.fontSize + "px";
  }
  parent.appendChild(element);
}
function randomColor () {
  return "rgb(" + random(256) + "," +
    random(256) + "," + random(256) + ")";
}
function random (integer) {
  return Math.floor(integer * Math.random())
}
export { drawCheckerBoard, newElement };

Second, here is the associated lisp code. This is the on-change functions of three button widgets on a dialog in a test project, where the first function draws a checker board, the second creates an HTML element in the dialog, and the third creates an HTML element on the CG screen. You could try this out by adding a form window to a new project, placing three button widgets in the upper-right area of the form window, and giving the button widgets these on-change functions. Also add a file named one.js to the project folder and put the JS code above into that file, and enter ("one.js") in the JavaScript Files to import widget on the CG/JS tab of the Project Manager dialog. Then run the project and generate the standalone app!

(defun draw-button-on-change (widget new-value old-value)
  (declare (ignorable widget new-value old-value))
  (call-js `((fun "drawCheckerBoard")
             (args ,(list (handle (parent widget)))))
           "one") ;; the pathname-name of the JS file
  t)
(defun new-sibling-button-on-change (widget new-value old-value)
  (declare (ignore new-value old-value))
  (new-element (handle (parent widget))
               (left widget)
               (+ (bottom (find-sibling :top-level widget)) 24)
               (width widget)(width widget))
  t)
(defun new-top-level-on-change (widget new-value old-value)
  (declare (ignore widget new-value old-value))
  (new-element 0 ;; the screen's handle is always zero
               60 60 200 200)
  t)
(defun new-element (parent-handle left top width height)
  (call-js `((fun "newElement")
             (args ,(list parent-handle left top width height)))
           "one")
  t)

can-paste

Generic Function, cg package

Arguments: window clipboard-format

the use of this function is deprecated as it does not in fact seem useful. Common Graphics never calls this overridable generic function internally. Applications that call it should instead keep track of which of its windows know how to paste the various data formats.

Returns true if (a) window knows how to paste an object of type clipboard-format and (b) a value for clipboard-format is currently available on the Windows clipboard (see available-clipboard-formats).

clipboard-format may be one of (:text :rich-text :pixmap).

See cg-rich-text.html for information on rich text editing in Common Graphics. See also cg-clipboard.html.


cancel-button

Generic Function, cg package

Arguments: dialog

If dialog has a cancel-button, it is returned by this function. nil is returned if dialog has no cancel-button. (Placing multiple cancel-buttons on a dialog is possible but not recommended. If a dialog has multiple cancel buttons, only one is returned by this function, but which one is returned cannot be determined.) See the description of the cancel-button class.


capitalize-if-symbol

Function, cg package

Arguments: object

Returns the print name of its argument (i.e. a string that is the printed representation of the object). If the argument is a symbol, the string is capitalized as if with string-capitalize. No changes are made to the string if the argument is not a symbol.


capitalize-object

Function, cg package

Arguments: object

Returns the print name of its argument (i.e. a string that is the printed representation of the object) after capitalizing the argument as if with string-capitalize.


capitalize-symbol

Function, cg package

Arguments: symbol

Returns the print name of its argument, which must be a symbol, after capitalizing it as if with string-capitalize.


capture-mouse

Generic Function, cg package

Arguments: window

Redirects all mouse events to window until released with release-mouse. See also with-mouse-captured.


caret

Generic Function, cg package

Arguments: caret-mixin

Returns the value of the caret of its argument (which must be a window that includes the caret-mixin class). The value may be either the symbol :solid, the symbol :gray, or a monochrome bitmap handle (as returned by aclwin:open-texture). :solid or :gray will produce a simple rectangular caret whose dimensions are determined by the caret-width and caret-height methods.

Carets are specific to Microsoft Windows, and caret code in an application will have no effect in CG/JS mode.


caret-blink-time

Function, cg package

Arguments:

Returns (and with setf sets) the current caret blink time. The units are milliseconds.


caret-height

Generic Function, cg package

Arguments: caret-mixin

Returns (or sets with setf) the height in pixels of the caret for the argument (a window with caret-mixin). If the caret is a bitmap, then this value is ignored.


caret-position

Function, cg package

Arguments: window

Returns the current position for the caret of window. Use setf to programmatically move the caret.


caret-width

Generic Function, cg package

Arguments: caret-mixin

Returns (or sets with setf) the width in pixels of the caret for the argument (a window with caret-mixin). If the caret is a bitmap, then this value is ignored.


cell-3d-border

Generic Function, cg package

Arguments: row column

This generic function returns whether the grid cell at the intersection of the specified grid-row and grid-column will be drawn with a pseudo-three-dimensional border. Applications may add cell-3d-border methods to determine which cells (if any) will have a 3d border. This border, if drawn, is in addition to the "regular" border (see border-width and default-cell-border-width).

If the returned value is nil (the default), then no 3d borders will be drawn. If it is the keyword :sunken-edge, then 3d borders will be drawn that appear sunken (making the grid cells appear raised). If it is t, then 3d borders will be drawn that appear raised (making the grid cells appear sunken).

The default method returns the value of the default-cell-3d-border property of the grid-row-section, the grid-column-section, or the grid-widget (in that order) that contains the specified cell, if any of those property values is non-nil, and otherwise it returns nil. (The default value of the default-cell-3d-border property is nil, so nil is returned from this default method if the property has not been specified for any of those objects.)


cell-and-sections-available

Function, cg package

Arguments: grid-row grid-column

Returns true if and only if available applied to grid-row, available applied to grid-column, and cell-available appliued to both grid-row and grid-column all return true.


cell-available

Generic Function, cg package

Arguments: row column

Returns true if this particular cell (as opposed to its row or column) is available. This default method calls the column's available-reader on the row's data-object.


cell-background-color

Generic Function, cg package

Arguments: row column

Returns the background-color for the cell specified by row and column. The value can be a color or nil, which means use the grid's background color.

If the value is a color, it must be an RGB color (as returned by make-rgb). Note that the value cannot be an HLS color (as returned by make-hls). If you use HLS colors, apply hls-to-rgb to them before setting this property, and apply rgb-to-hls to get the HLS equivalent of a RGB value.

An application can supply cell-background-color methods that return the color to use for cells at the intersection of row and column subclasses. The default method will return a color that was specified by a call to (setf cell-color), if any, or else a color that was specified by background-color-one or background-color-two, if any.


cell-box

Generic Function, cg package

Arguments: row-section column-section row column row-num column-num &optional data-area-only-p

Returns the interior region (excluding borders) of a grid cell in window coordinates, unclipped.


cell-click

Generic Function, cg package

Arguments: grid-widget buttons column-section column-section-border-p column column-num column-border-p x row-section row-section-border-p row row-num row-border-p y &optional trigger-key

This generic function is called when a cell in a grid-widget is clicked. cell-click methods allow the user to initiate arbitrary actions by clicking in particular cells. Often the action is to prompt the user in some way for a new value for the clicked cell; a cell-click method may then call write-cell-value to write the new value into the application's domain data.

If a particular grid cell is to respond to mouse clicks, and the click is not handled by one of the built-in grid-column types such as combo-box-column-mixin, then the application must supply a cell-click method for cells of that row and column type.

grid-widget, row-section, column-section, row, and column are the grid, grid sections, and grid subsections that contain the grid cell that was clicked. row-number and column-number are non-negative integers that indicate the sub-row or sub-column that was clicked when the subsection is replicated (due to having a section-count property that is greater than one); zero indicates the first subsection, and these numbers are always zero for non-replicated subsections.

x and y are the clicked position within the cell, where zero, zero indicates the upper left corner of the cell (inside the borders). The various ...-border-p arguments are true if the click was within *grid-border-mouse-slack* of the right or bottom border of the particular section or subsection.

If trigger-key is true, this indicates that an actual mouse click was not done, but rather that a special key was pressed to emulate a mouse click with the keyboard. In particular, cell-click is called when the user presses the ENTER key or the SPACE bar (unless the user is in a special mode such as typing into an editable-text-column-mixin cell). trigger-key is then the integer code of the key that was pressed, and is therefore the value of either vk-return or vk-space.

A cell-click method could respond differently to each of these keys; for example, a combo-box-column-mixin cell will drop its choice list when SPACE is pressed, as if the user clicked on the cell's arrow, but will start a text edit when ENTER is pressed (assuming that the column's typable property is on), as if the user clicked in the text area of the cell.


cell-color

Generic Function, cg package

Arguments: grid-widget row-name-or-index column-name-or-index &key (row-number 0) (column-number 0) (row-section-name :body) (column-section-name :body)

Returns the background color of a grid-widget cell, or sets the background color of a cell with the setf of this function. The setf function is a more convenient way to specify the background color of an arbitrary cell than writing cell-background-color methods that specialize on custom row and column subclasses.

cell-color calls cell-background-color to find the color to return, which will be the color that was supplied by (setf cell-color) if that function was used to specify a color for this cell and no more specific cell-background-color method for the cell returns a color.

The value that's passed to (setf cell-color) should be an RGB color object, as made with make-rgb. See the similar function cell-value for the valid values of the other arguments.


cell-draggable-p

Generic Function, cg package

Arguments: row column

Returns true if the value in the cell can be dragged from the cell. Returns nil otherwise.


cell-font

Generic Function, cg package

Arguments: grid-row grid-column

This generic function is called whenever a grid-widget cell is drawn, to determine the font that will be current when draw-cell is called for the cell. A font should be returned to be used for the cell that lies at the intersection of the specified row and column. An application may add cell-font methods to determine the current font for various cells. Call make-font-ex or make-font to make the font to return.

The default method calls the font-reader function of the grid-column on the data-object of the grid-row if both of those properties have been supplied by the application, and otherwise returns the font property of the column if it is non-nil, and otherwise returns the font property of the whole grid-widget.

While a custom draw-cell method could simply call with-font to establish the font on the fly, defining cell-font methods may be needed when built-in draw-cell methods are used. For example, a default grid cell will draw a centered string from the value returned by read-cell-value, without the application supplying a custom draw-cell method. And when using the grid-column mixin classes that supply built-in grid cell widgets, such as editable-text-column-mixin and combo-box-column-mixin, built-in draw-cell methods are always used, and so a custom cell-font method can control the font of the otherwise built-in drawing behavior of those cells.


cell-foreground-color

Generic Function, cg package

Arguments: row column

Returns the foreground-color for the cell specified by row and column. The value must be a color or nil, which means use the grid's foreground color.

If the value is a color, it must be an RGB color (as returned by make-rgb). Note that the value cannot be an HLS color (as returned by make-hls). If you use HLS colors, apply hls-to-rgb to them before setting this property, and apply rgb-to-hls to get the HLS equivalent of a RGB value.


cell-horizontal-border-color

Generic Function, cg package

Arguments: grid-row grid-column

The line that is drawn as a border between two grid-rows of a grid-widget is typically drawn in a single color from the left side of the whole grid to the right side. If it is desirable instead to draw the line in different colors where it crosses particular grid-columns, then an application can supply cell-horizontal-border-color methods to specify these colors. An application could also call this function, though there is probably no need to do so.

This generic function is called internally when drawing the cell at the intersection of grid-row and grid-column, to see if the border along the bottom of the cell should be drawn in a different color than the general color of that border (which is returned by effective-border-color). The method may return either an RGB color object in order to use that color (see make-rgb), or nil to default to the border's general color, or t to use the cell's effective-background-color. The default method returns nil.

The special value of t (to draw the border with the cell's background color) will effectively remove the border from the bottom of the cell. This may be useful for making two contiguous cells appear as a single cell (though they will still behave as separate cells when moving the keyboard focus, for example). If it is desired to draw a single picture in the interior of the combined cells, then any graphic that lies across the border between the cells should be drawn in the draw-cell method for each of the cells; this will ensure that the graphic is drawn whenever needed. The employee grid example on the Examples tab of the Navigator dialog contains a fancy example of this, to cover a few tricky small aspects of this advanced technique.


cell-horizontal-justification

Generic Function, cg package

Arguments: row column

Returns the type of horizontal alignment to use when text is drawn in the grid cell at the intersection of the specified grid-row and grid-column. The value may be :left, :center, or :right. The default method returns the horizontal-justification property of the grid-column.

An application can control this alignment by setting the horizontal-justification property of grid columns and/or by writing cell-horizontal-justification methods.


cell-horizontal-padding

Generic Function, cg package

Arguments: grid-row grid-column

Returns a non-negative integer indicating the breadth (in pixels) of margins along the left and right sides of a grid cell (specified by the grid-row and grid-column arguments) in a grid-widget to reserve between the cell's border and whatever is drawn in the cell. The built-in draw-cell methods call this function to determine where to draw text in the cell; these built-in draw-cell methods include the ones for the special widget mixin columns such as editable-text-column-mixin, as well as the default draw-cell method that simply draws a string from the object that is returned by read-cell-value and data-read-converter.

The default cell-horizontal-padding method returns 4. An application may supply methods to change the padding for built-in cell types, and also for custom cell types if the associated custom draw-cell methods call this generic function and use the returned values (which is not required).

See also cell-vertical-padding.


cell-key-down

Generic Function, cg package

Arguments: grid-widget row-section column-section row column row-number column-number buttons key-code

This generic function is called whenever the user presses a key on the keyboard while a grid-widget has the keyboard focus, except when the pressed key is one that is used in a special reserved way for grid navigation. These exceptions include tab, shift-tab, enter, space, page-down, page-up, home, end, the four arrow keys, and delete. In addition, this generic function is never called while the user is typing into an editable-text-column-mixin cell.

An application may add cell-key-down methods to initiate some action when the user presses particular keys while particular cells have the keyboard focus. Often this action is to prompt the user in some way for a new value for the grid cell, or to automatically insert particular grid values depending on the key that was pressed. The cell-key-down methods may call write-cell-value to update the application's data in some way.

grid-widget, row-section, column-section, row, and column are the grid, grid sections, and grid subsections that contain the grid cell that currently has the keyboard focus. row-number and column-number are non-negative integers that indicate the sub-row or sub-column that has the focus when the subsection is replicated (due to having a section-count property that is greater than one); zero indicates the first subsection, and these numbers are always zero for non-replicated subsections.

buttons is an integer that indicates the mouse buttons and shift keys that are down, and is some logior'ed combination of the values of these bit-flag constants: left-mouse-button, middle-mouse-button, right-mouse-button, first-x-button (see *ignore-mouse-x-buttons*), second-x-button (see *ignore-mouse-x-buttons*), shift-key, control-key, and alt-key.

key-code is an integer indicating the particular key that was pressed. If an alphanumeric character appears on the key, then key-code is the char-int of that character. Otherwise, key-code is the value of one of the character name constants beginning with "vk-".

The value of the constant key-names is a list of all of the "vk-" character names.

Here is the default method, which does nothing:

(defmethod cell-key-down 
    ((grid-widget grid-widget)(row-section grid-row-section)
                          (column-section grid-column-section)
                          (row grid-row)(column grid-column)
                           row-number column-number 
                           buttons key-code)
   (declare (ignore row-number column-number buttons key-code))
   nil)

cell-mouse-in

Generic Function, cg package

Arguments: grid-widget column-section column row-section row

This function is called when the mouse cursor moves over a cell. The default method does nothing.


cell-mouse-out

Generic Function, cg package

Arguments: grid-widget column-section column row-section row

This function is called when the mouse cursor moves out of a cell. The default method does nothing.


cell-selected

Generic Function, cg package

Arguments: row column

Returns true if this particular cell (as opposed to its row or column) on a grid-widget is selected. The default method calls the column's selected-reader on the row's data-object, if those two properties are supplied, and otherwise does nothing. An application may add cell-selected methods to determine the selected state of individual cells. Alternately, set the selected property of whole grid-rows and grid-columns.


cell-selected-background-color

Generic Function, cg package

Arguments: grid-row grid-column

Returns the color in which to draw the background of the grid-widget cell at the intersection of the specified grid-row and grid-column if the cell is currently selected (see cell-selected, selected, selectable, and selected-reader). The value should be an RGB color object (see make-rgb).

The default method returns the value returned by system-highlight-background-color, which is a color that the end user has specified in the Windows Control Panel. An application may add cell-selected-background-color methods in order to override the Control Panel defaults for some or all grid cells.

See also cell-selected-foreground-color, cell-unavailable-foreground-color, and cell-background-color.


cell-selected-foreground-color

Generic Function, cg package

Arguments: grid-row grid-column

Returns the color in which to draw the foreground of the grid-widget cell at the intersection of the specified grid-row and grid-column if the cell is currently selected (see cell-selected, selected, selectable, and selected-reader). The value should be an RGB color object (see make-rgb).

The default method returns the value returned by system-highlight-foreground-color, which is a color that the end user has specified in the Windows Control Panel. An application may add cell-selected-foreground-color methods in order to override the Control Panel defaults for some or all grid cells.

See also cell-selected-background-color and cell-foreground-color.


cell-style

Generic Function, cg package

Arguments: calendar-widget

This property of a calendar widget is a cell-style object that determines how regular cells are drawn.

See also the calendar class and the function ask-user-for-date.


cell-style-current-date

Generic Function, cg package

Arguments: calendar-widget

This property of a calendar widget is a cell-style object that determines how today's date is drawn.

See also the calendar class and the function ask-user-for-date.


cell-style-other-month

Generic Function, cg package

Arguments: calendar-widget

This property of a calendar widget is a cell-style object that determines how dates in the previous and next months are drawn.

See also the calendar class and the function ask-user-for-date.


cell-style-selected

Generic Function, cg package

Arguments: calendar-widget

This property of a calendar widget is a cell-style object that determines how the currently selected cell is drawn.

See also the calendar class and the function ask-user-for-date.


cell-style-under-mouse

Generic Function, cg package

Arguments: calendar-widget

This property of a calendar widget is a cell-style object that determines how the cell that's currently under the mouse is drawn.

See also the calendar class and the function ask-user-for-date.


cell-unavailable-foreground-color

Generic Function, cg package

Arguments: grid-row grid-column

Returns the color in which to draw the foreground of the grid-widget cell at the intersection of the specified grid-row and grid-column if the cell is currently unavailable (see cell-available, available, available-reader, and cell-and-sections-available).

The default method returns the value returned by system-disabled-color, which is a color that the end user has specified in the Windows Control Panel. An application may add cell-unavailable-foreground-color methods in order to override the Control Panel defaults for some or all grid cells.

The value must be an RGB color (as returned by make-rgb). Note that the value cannot be an HLS color (as returned by make-hls). If you use HLS colors, apply hls-to-rgb to them before setting this property, and apply rgb-to-hls to get the HLS equivalent of a RGB value.


cell-value

Generic Function, cg package

Arguments: grid-widget row-name-or-index column-name-or-index &key (row-number 0) (column-number 0) (row-section-name :body) (column-section-name :body)

Returns the value of a grid-widget cell, or sets the value of a cell with the setf of this function.

This function allows specifying a cell value by passing the names or indexes of the grid rows and columns (and sections), rather than passing the row and column objects as with read-cell-value and write-cell-value. This may be more convenient than finding the objects to pass. cell-value calls read-cell-value after finding the named subsections, and (setf cell-value) calls write-cell-value.

row-name-or-index and column-name-or-index should each be either the symbol that names the row or column or the zero-based index of the row or column within its section. row-number and column-number are the sub-indexes within a replicated subsection.

row-section-name and column-section-name should be the symbols that name the sections that the row and column are in. The default is :body for the typical case where you are accessing a main section whose name is :body, such as with a grid-widget that is created interactively by placing it onto a form window (see cg-grid-widget-simplified-tutorial.html).


cell-vertical-border-color

Generic Function, cg package

Arguments: grid-row grid-column

The line that is drawn as a border between two grid-columns of a grid-widget is typically drawn in a single color from the top of the whole grid to the bottom. If it is desirable instead to draw the line in different colors where it crosses particular grid-rows, then an application can supply cell-vertical-border-color methods to specify these colors. An application could also call this function, though there is probably no need to do so.

This generic function is called internally when drawing the cell at the intersection of grid-row and grid-column, to see if the border along the right side of the cell should be drawn in a different color than the general color of that border (which is returned by effective-border-color). The method may return either an RGB color object in order to use that color (see make-rgb), or nil to default to the border's general color, or t to use the cell's effective-background-color. The default method returns nil.

The special value of t (to draw the border with the cell's background color) will effectively remove the border from the right side of the cell. This may be useful for making two contiguous cells appear as a single cell (though they will still behave as separate cells when moving the keyboard focus, for example). If it is desired to draw a single picture in the interior of the combined cells, then any graphic that lies across the border between the cells should be drawn in the draw-cell method for each of the cells; this will ensure that the graphic is drawn whenever needed. The employee grid example on the Examples tab of the Navigator dialog contains a fancy example of this, to cover a few tricky small aspects of this advanced technique.


cell-vertical-justification

Generic Function, cg package

Arguments: row column

Returns the type of vertical alignment to use when text is drawn in the grid cell at the intersection of the specified grid-row and grid-column. The value may be :top, :center, or :bottom. The default method returns the vertical-justification property of the grid-column.

An application can control this alignment by setting the vertical-justification property of grid columns and/or by writing cell-vertical-justification methods.


cell-vertical-padding

Generic Function, cg package

Arguments: grid-row grid-column

Returns a non-negative integer indicating the breadth (in pixels) of margins along the top and bottom sides of a grid cell (specified by the grid-row and grid-column arguments) in a grid-widget to reserve between the cell's border and whatever is drawn in the cell. The built-in draw-cell methods call this function to determine where to draw text in the cell; these built-in draw-cell methods include the ones for the special widget mixin columns such as editable-text-column-mixin, as well as the default draw-cell method that simply draws a string from the object that is returned by read-cell-value and data-read-converter.

The default cell-vertical-padding method returns 2. An application may supply methods to change the padding for built-in cell types, and also for custom cell types if the associated custom draw-cell methods call this generic function and use the returned values (which is not required).

See also cell-horizontal-padding.


cell-widget

Generic Function, cg package

Arguments: grid-row grid-column row-number column-number

Returns a number of values that indicate which of the several built-in cell widgets should appear in particular grid-widget cells, and what attributes those widgets should have. The default method does nothing, so an application must add its own cell-widget methods in order to use the built-in cell widgets with this approach.

An alternative approach is to use the various widget-column-mixin subclasses along with the widget-row-mixin class. That approach is more object-oriented, but also limits the built-in cell widgets to particular columns for each type of widget.

The IDE's Navigator dialog contains a complete example of the cell-widget approach, called Grid-widget: using built-in cell widgets in ARBITRARY cells.

The first value returned from a cell-widget method should be a keyword that indicates which type of widget to use in the cell that is indicated by the arguments to cell-widget. The possible values are :button, :static-text, :editable-text, :check-box, :combo-box, :lamp, and :pixmap. For more information on how each of these widgets works, please refer to the associated widget-column-mixin class shown below (even though these classes are not used at all when writing cell-widget methods):

The rest of the multiple values that a cell-widget method should return supply various attributes of the cell's widget. These values depend on which type of widget is being used. Most of these values correspond to properties of the various widget-column-mixin subclasses, though the cell-widget approach does not use those mixin classes. Since the cell-widget approach has no grid-column object on which to hang these property values, we must return them as multiple values from cell-widget methods instead.

Here are the multiple values that a cell-widget method should return for each type of widget. This list includes links to the corresponding widget-column-mixin properties that they emulate, where applicable, for more information.

These returned values cover only the properties that are unique to the built-in cell widgets. Other attributes of the cell will still be determined by general grid-widget generic functions such as read-cell-value, write-cell-value, cell-font, cell-background-color, cell-horizontal-justification, and so on. See the grid-widget class for a complete overview.

cell-widget methods may be called frequently, so to avoid generating a lot of garbage it is advisable to return static values rather than values that are newly consed on each call.

There is an example using cell-widget on the Examples tab of the Navigator dialog.

See the grid-widget class for an overview of writing grid-widget code.


cell-wrapped-p

Generic Function, cg package

Arguments: row column

Returns whether text in the cell will wrap (at word boundaries) to multiple lines of text.

See the grid-widget class for an overview of writing grid-widget code.


center-all

Generic Function, cg package

Arguments: lamp

Returns the value of the center-all property of a lamp widget. The value may be be specified at creation time with the center-all initarg, or anytime later by calling (setf center-all).

If the center-all property is nil, as it is by default, then the lamp images are positioned by the outer margin properties from the edge of the widget on any sides of the lamp image where there are no labels, leaving the rest of the widget's area for the labels. That may be useful for aligning the lamp images of multiple widgets by simply aligning the widgets themselves, without making sure that the widgets are all the same size. If the center-all property is true, then the lamp images and labels are centered as a unit within the widget's area. That may be especially useful when the lamp is used in a grid-widget cell, to keep the widget centered as the grid-widget cell changes in size. (When there are no label strings, the lamp images are always centered.)


center-all-modal-dialogs-on-screen

Generic Function, cg package

Arguments: configuration

Returns (or sets with setf) the value of the center-all-modal-dialogs-on-screen configuration property.

This property affects modal dialogs displayed by utility functions such as ask-user-for-choice-from-list. Modal dialogs created by application code can be positioned wherever the application likes before they are shown. But applications do not have a handle on built-in modal dialogs and so cannot specify their positions directly. This property gives some measure of control over the placement of such dialogs.

If the typical conventions allowed by this configuration option are not adequate, the built-in utility dialogs can be positioned however you like by writing a position-utility-dialog method.

The value of this property of the current configuration can be t, nil, or :on-owner, which is the default.

If the value is :on-owner, the dialog is centered on the owner window that the application passes to the various utility dialog functions. Such modal dialogs are displayed by functions like ask-user-for-choice-from-list.

If the value is t (or, indeed, any true value other than :on-owner), modal dialogs are positioned in the center of the screen (absent overriding specification of another location). If the value is nil, modal dialogs are placed near the upper left corner of the owner.

Note that for Common Dialogs (implemented by the operating system and invoked by functions such as ask-user-for-new-pathname), Common Graphics does not know how large the dialogs are and therefore cannot center them; therefore, for Common Dialogs, the :on-owner option behaves like nil to position the dialogs at or near the upper left corner of the owner window.

The current configuration is the value of (configuration *system*). (See configuration and *system*.)

See also position-utility-dialog


center-all-nodes

function, cg package

Arguments: nodes center-x-reader center-y-reader center-writer width-reader height-reader canvas-left canvas-top canvas-right canvas-bottom &key canvas animate (steps 8) redisplay-function cancel-function

This function modifies the nodes passed in a list as the value of the nodes argument. The return value of this function is not defined.

This utility function might be useful when using the function graph-layout to draw graphs and handle mouse events on them. The arguments (except for steps, defined below) should be the same as the same-named arguments to graph-layout. See that function for more information.

This function will call the center-writer function that is passed to it on each of the nodes so as to center the entire set of nodes within the rectangular region that's defined by canvas-left, canvas-top, canvas-right, and canvas-bottom.

One argument to this function that graph-layout does not have is the steps argument. This is the number of incremental steps at which the redisplay-function will be called to draw the entire graph, along the path between the current node positions and their new centered positions. The default value is 8.


center-box-on-page

Function, cg package

Arguments: stream width height &optional dialog-units-p

Returns a box (dimensions width and height) centered on the page of stream, relative to the current origin. If dialog-units-p is true, the coordinates are assumed to be in dialog units rather than pixels.


center-box-on-screen

Function, cg package

Arguments: width height &optional dialog-units-p

Returns a box (dimensions width and height) centered on the screen. If dialog-units-p is true, the coordinates are assumed to be in dialog units rather than pixels.


center-box-on-window

Function, cg package

Arguments: window width height &optional dialog-units-p

Returns a box (dimensions width and height) centered on the window relative to the current origin. If dialog-units-p is true, the coordinates are assumed to be in dialog units rather than pixels.


center-justify

Function, cg package

Arguments: text-edit-pane

Calls (setf justification) on text-edit-pane (a text-edit-pane) with the value :center. This is called by one of the rich-edit-multipic buttons, but could be called in other ways as well.


center-modal-children

Generic Function, cg package

Arguments: window

Called by the default position-utility-dialog method to decide which convention to use for positioning a utility dialog. The default method simply returns the value of the center-all-modal-dialogs-on-screen configuration option, which is either nil, t, or :on-owner. An application could add methods on this generic function to override the global configuration default for particular owner windows. The method should still return one of the three possible values of center-all-modal-dialogs-on-screen if the default position-utility-dialog method is used.


center-to-box

function, cg package

Arguments: position width height &key box

Returns a box whose center is at the specified position (see make-position) and which has the specified width and height.

The box argument, if specified, should be either a box (see make-box) or nil. If a box, then that box is modified and returned. Otherwise a new box is created and returned.


center-to-box-x-y

function, cg package

Arguments: center-x center-y width height &key box

Returns a box whose center is at the position specified by center-x and center-y, and which has the specified width and height.

The box argument, if specified, should be either a box (see make-box) or nil. If a box, then that box is modified and returned. Otherwise a new box is created and returned.


center-window

Generic Function, cg package

Arguments: window &key on-parent return-only width height

Moves a window so that it is centered over the interior of its owner or parent. Returns a box that indicates the new exterior of the window.

window should be an instance of the basic-pane class or one of its subclasses.

If on-parent is true, then the window is centered over its parent, and otherwise it is centered over its owner. The default is nil. (The parent and owner of a window are different only when the window is a top-level owned window, in which case the parent is the screen and the owner is the owner window.)

If return-only is true, then the window is actually not moved at all, but the box to where it would have been moved is still returned. If nil (the default), then the window is moved and its new exterior box is returned.

width and height may each be nil (the default) to use the current width or height of the window, or else a positive integer to indicate a new width or height to which to resize the window while centering it.

See also the :centered argument to make-window and the centered property.


centered

Generic Function, cg package

Arguments: window

Returns whether a window was initially centered over the interior of its owner or parent when it was created.

(setf centered) may be called to change the value, though this is useful only for a form in an IDE project, where it indicates whether the running window that is created from the form will be centered. A centered property appears in the inspector for a form (or other window), where it may be set interactively.

When creating a window programmatically, centering is achieved by passing the :centered argument to make-window.

The value may be either nil (the default) for no centering, :on-parent to center over the parent, or any other true value to center over the owner. (The parent and owner of a window are different only when the window is a top-level owned window, in which case the parent is the screen and the owner is the owner window.)


cg-argument-checking

function, cg package

Arguments:

Returns a boolean value indicating whether some Common Graphics functions are currently checking the validity of their arguments whenever they are called. The setf of this function can be called to turn argument checking on or off.

Common Graphics doesn't do argument checking by default, for efficiency reasons. But you can turn it on for debugging purposes with (setf (cg-argument-checking) t), and turn it back off afterward with (setf (cg-argument-checking) nil).

Even when enabled, this facility will check arguments only in a small subset of all user CG functions. These are mostly low-level functions where invalid arguments may be especially confusing or might even corrupt the Lisp. For example, if you called (setf box-right) on a position object, that would write past the end of the shorter position foreign structure and corrupt memory there, though with this argument-checking facility turned on it would instead signal an informative error.


cg-commit

Function, cg package

Arguments: window &key (confirm t)

This function is called by the :commit-button widget of an object-editor dialog (see command-buttons), and may also be called directly by application code.

It simply calls db.ac:commit if the user confirms in a modal dialog, and displays a couple of status-bar messages in the specified window, which would typically be an object-editor. The confirmation dialog is skipped if the confirm argument is passed as nil.


cg-emacs-comtab

function, cg package

Arguments:

Returns a comtab (command table) that contains a subset of the IDE editor keystrokes when ide:editor-mode is :emacs. This comtab could be given to a text-edit-pane in a Common Graphics application to provide the IDE editor's general text-editing keystrokes that are not specific to the IDE.

See cg-host-comtab for a table of all of the keystrokes that are provided by this comtab as well as that one.


cg-host-comtab

function, cg package

Arguments:

Returns a comtab (command table) that contains a subset of the IDE editor keystrokes when ide:editor-mode is :host. This comtab could be given to a text-edit-pane in a Common Graphics application to provide the IDE editor's general text-editing keystrokes that are not specific to the IDE. Example:

(setf (comtab my-text-edit-pane)(cg-host-comtab))

Below is a table of the keystrokes that are defined by this comtab as well as by cg-emacs-comtab. The symbols in the left column are functions, but most of them are not exported from the cg package for general application use (though perhaps they should be). They are listed here simply as command names that also appear in the IDE's Help menu | Shortcut Keys dialog.

For brief descriptions of what each of these functions does, see the documentation for the Shortcut Keys.

Function Host Comtab Emacs Comtab
backward-character --- Ctrl+B
backward-delete-line Alt+Backspace ---
backward-delete-sexp Ctrl+Shft+Backspace ---
backward-kill-line --- Alt+K
backward-kill-sexp --- Ctrl+Alt+Backspace
backward-kill-word --- Ctrl+Backspace

Alt+Backspace

Alt+H
backward-list --- Ctrl+Alt+P
backward-sexp Ctrl+Alt+Left

Alt+Left
Ctrl+Alt+Left

Ctrl+Alt+B
backward-up-list Ctrl+Shft+Up Ctrl+Alt+U

Ctrl+Alt+Down
backward-word --- Alt+B

Alt+Left
beginning-of-buffer --- Alt+Shft+Comma
beginning-of-line --- Ctrl+A
beginning-of-next-definition Alt+Down

Ctrl+Alt+Down
Ctrl+Alt+Close-Square-Bracket
beginning-of-this-or-previous-definition Alt+Up

Ctrl+Alt+Up
Ctrl+Alt+Open-Square-Bracket

Ctrl+Alt+A
capitalize-selection --- Alt+C
copy-command Ctrl+C Alt+W
cut-command Ctrl+X Ctrl+W
delete-horizontal-space Ctrl+Slash Ctrl+Slash
delete-indentation --- Ctrl+6
delete-line Alt+Delete ---
delete-next-character --- Ctrl+D
delete-previous-character Ctrl+H Ctrl+H
delete-sexp Ctrl+Shft+Delete ---
delete-surrounding-whitespace Alt+Slash Alt+Slash
down-list --- Ctrl+Alt+D
downcase-selection --- Alt+L
end-of-buffer --- Alt+Shft+Period
end-of-definition --- Ctrl+Alt+E
end-of-line --- Ctrl+E
exchange-to-mark-command Alt+Shft+K Ctrl+X Ctrl+X

Ctrl+3
forward-character --- Ctrl+F
forward-list --- Ctrl+Alt+N
forward-sexp Alt+Right

Ctrl+Alt+Right
Ctrl+Alt+F

Ctrl+Alt+Right
forward-up-list Ctrl+Shft+Down Ctrl+Alt+)
forward-word --- Alt+F

Alt+Right
illegal-operation --- Ctrl+G

Alt+G

Ctrl+X Ctrl+G
insert-empty-list Ctrl+Shft+3 Alt+9
insert-empty-string Ctrl+Shft+2 Alt+Shft+2
just-one-space Ctrl+Alt+Slash Ctrl+Alt+Slash
kill-line --- Ctrl+K
kill-sexp --- Ctrl+Alt+K
kill-word --- Alt+D
mark-command Alt+Shft+J Ctrl+2
newline Ctrl+Return Return

Ctrl+M

Shft+Return
newline-and-indent Return

Shift+Return
Ctrl+J
next-line --- Ctrl+N
next-page --- Ctrl+V
open-line --- Ctrl+O
paste-command Ctrl+V Ctrl+Y
previous-line --- Ctrl+P
previous-page --- Alt+V
recenter Ctrl+Space Ctrl+L
reindent-sexp --- Ctrl+Alt+Q
reindent-single-line Tab Tab
select-all Ctrl+A Alt+Shft+A
select-current-sexp Ctrl+Shft+Return Ctrl+Shft+Return
select-to-mark-command Alt+Shft+L Ctrl+4
transpose-characters Ctrl+Quote Ctrl+T
transpose-sexp Alt+Quote ---
undo-command --- Ctrl+X Ctrl+U
upcase-selection --- Alt+U

cgjs-client-option

Function, cg package

Arguments: option-name

Returns one of the values in *cgjs-client-options*. Calling the setf of this function directly has no effect in the usual scenarios, and there are other facilities for modifying these options.


cgjs-options

Generic Function, cg package

Arguments: project

Returns a cgjs-options object that stores CG/JS server options for a project. These are typically set interactively in the CG/JS tab of the Project Manager but this object can be used for reading or setting them programmatically.


cgjs-server-option

Function, cg package

Arguments: option-name

Returns one of the values in *cgjs-server-options*.

Calling the setf of this function directly is not supported. It would likely have no effect because the values have already been used once lisp has started up, and it might cause unforseen confusion.


cg-process-wait

Function, cg package

Arguments: whostate function &rest args

This function can be called instead of mp:process-wait whenever windowing events may need to be handled during the wait, and the code might be run in CG/JS mode. It can be called with the same arguments as mp:process-wait, and so existing calls to mp:process-wait can be made to work in CG/JS mode in this situation by simply substituting the name of this function.

When running in Windows desktop mode, this function simply calls mp:process-wait, because that function knows how to how to handle Microsoft Windows events during the wait. When running in CG/JS mode, CG uses a custom loop that both handles CG/JS events and exits when the wait function returns true.


cg-rollback

Function, cg package

Arguments: &key (confirm t) window

This function is called by the :rollback-button widget of an object-editor dialog (see command-buttons), and may also be called directly by application code.

It calls db.ac:rollback if the user confirms in a modal dialog, and displays a couple of status-bar messages in the specified window if one is passed. The confirmation dialog is skipped if the confirm argument is passed as nil.

It then ensures that any object-editor dialogs and class-grid widgets in the environment are brought up to date, by calling uncache-instances-with-pretty-names with the :all argument, and then calling update-all-class-interface-widgets. It is strongly recommended that any application that uses object-editors and/or class-grids call this function rather than calling db.ac:commit directly, or else to call those two exported functions that cg-rollback calls. Otherwise the interface objects may be left in a broken state.


cg-timer

Function, cg package

Arguments:

Returns a built-in timer that is used internally by Common Graphics for a variety of purposes and which normally is always active (but see use-cg-timer). See cg-timer-interval. See also cg-timers.html for more information on timers.


cg-timer-interval

Generic Function, cg package

Arguments: configuration

The internal built-in timer (returned by cg-timer) uses a preset interval for most tasks. This function returns (or sets with setf) that interval. The initial value of the interval is 500 (milliseconds).

This value could be modified by an application to change the quickness with which Common Graphics does a few things such as generating a mouse-out event when the mouse cursor goes outside of any lisp window, and the speed with which the IDE reports the current package and tracing/profiling flags at the right side of the IDE menubar window. Smaller values will make these actions faster, but may bog down other processing if too frequent. cg-timer-interval is a property of the configuration class. The current configuration is the value of

(configuration *system*)

See cg-timers.html for more information on timers.


change-case-like-reader

Function, cg package

Arguments: string

Changes the case of string as needed to match the case in which symbols are normally read in the *current-case-mode*. Specifically, this will lowercase strings in :case-sensitive-lower mode, uppercase strings in :case-sensitive-upper mode, and (in the case-insensitive modes) just return the string as is.


change-outline-item-availability

Generic Function, cg package

Arguments: outline item available

Establishes (by the value of the available argument) whether an outline-item is available to the user, given an outline-item structure.


change-outline-item-value-availability

Generic Function, cg package

Arguments: outline item-value available

Establishes (by the value of the available argument) whether an outline-item is available to the user, given the value of an outline-item.


char-from-line-number

Generic Function, cg package

Arguments: stream line-number

Returns an integer that's the index of the first character in the line of text that's specified by line-number. An exception is that nil is returned if line-number is equal to or greater than the number-of-text-lines in stream, because there is no character index there.

line-number should be a non-negative integer, with zero indicating the first line of text. stream can be a multi-line-editable-text widget or a text-edit-pane.

See also line-number-from-char.


char-to-key-name

Function, cg package

Arguments: char &key return-comtab-event

This function takes a lisp character object as an argument and returns the name of the key that is pressed in order to type that character. This name may be a lisp character object such as #\A or one of the vk-... constants such as vk-period. A second returned value is an integer which is a logior'ed value indicating which shift keys are used with the returned key in order to type the character; the logior'ed values are the values of the symbols shift-key, control-key, and alt-key (whichever of those keys are down).

Examples:

> (char-to-key-name #\*)
#\8
4         (4 is the value of shift-key)
> (char-to-key-name #\>)
vk-period
4

If the keyword argument return-comtab-event is true, then instead of the two returned values detailed above a single value is returned. This value is an event-synonym specifier list in the format that is passed to set-event-function or the :event-synonym initarg of a menu-item.

Examples:

> (char-to-key-name #\* :return-comtab-event t)
(shift-key #\8)
> (char-to-key-name #\> :return-comtab-event t)
(shift-key vk-period)

The association of shifted special characters with unshifted characters is more or less standard on all United States keyboards but can be different (from the US standard) on non-US keyboards. This function may be needed for applications that must work on such non-US-standard keyboards.


character-format

Generic Function, cg package

Arguments: window &optional scratch-character-format

The function returns a character-format instance representing the character format of the selected text, if any, and otherwise of the character just before the current text cursor position in window. If scratch-character-format is supplied, it should be a character-format instance which is then filled in and returned. Note that using scratch-character-format avoids consing a new character-format instance.

The setf function sets the character formatting of the currently selected text of window to reflect character-format, which should be a character-format instance.

See cg-rich-text.html for information on rich text editing in Common Graphics. See also get-character-format, which returns the attributes as multiple values rather than as a character-format object. See also get-character-format, which returns the attributes as multiple values rather than as a character-format object.


character-index-at-position

Function, cg package

Arguments: text-edit-pane position

Returns the zero-based index of the character at position in text-edit-pane if that pixel position is currently scrolled into view, and otherwise returns nil. If there is no character at the specified position (but that position is scrolled into view), then the index of the nearest character is returned.

text-edit-pane should be a text-edit-pane or rich-edit-pane.

position should be a position object (see make-position) in stream coordinates, meaning that it is measured from the upper-left corner of the scrollable contents of the window, and so the value is not affected by the current scroll-position of the window.

(The functionality that is exported by the Windows rich-edit control, which we use for all text-edit-panes in Windows, does not appear to provide a way to determine the character when it is not scrolled into view. There is also no way to programmatically scroll this control to an arbitrary pixel position (in version 1.0), though set-first-visible-line will scroll a particular line of text to the top.)

See also position-of-character-index.


character-message

Generic Function, cg package

Arguments: window buttons character

This generic function is called when the user types a graphical character, unless a virtual-key-down method overrides the default behavior. An application may add methods to this generic function to respond to keyboard events in its windows.

window is the window that had the keyboard focus when the event occurred. The keyboard focus is usually indicated by some sort of highlighting.

buttons is an integer indicating which mouse buttons and shift keys were down when the event occurred. The value is the result of applying logior to the values of the following bit-flag variables:

Other bits might be turned on as well, so functions such as logtest should be used to determine whether a particular mouse button or shift key was down; for example,

(logtest right-mouse-button buttons) 

will return true if and only if the right mouse button was down. For "down" events, the value includes the button or key being pressed now; for "up" events, the value does not include the button or key being released.

character is the character that was typed. It is always a Common Lisp character object.

While a keypress will always cause virtual-key-down and virtual-key-up to be called, it will cause character-message to be called only under certain conditions. First, the keypress must indicate a graphical character. second, one of the following must be true:

  1. The window in which the key was pressed is a dialog-mixin instance or a child or other descendant of a dialog-mixin instance.

  2. The default virtual-key-down method must run (since this method tells the operating system to generate a character message from the virtual-key-down message).

Therefore, if an application adds a virtual-key-down method for a window that is not on a dialog, and this method does not call (call-next-method) for a particular keypress, then the default virtual-key-down method is not called, and therefore character-message will not be called for that keypress.

See cg-events.html for information about event handling in Common Graphics.


chart-item-id-equality-test

Generic Function, cg package

Arguments: chart-widget

Returns the value of the chart-item-id-equality-test property of a chart-widget. The value may be set at creation time by passing the :chart-item-id-equality-test initarg, or any time later by calling (setf chart-item-id-equality-test).

The value of this property is a function (or a the name of a function) that should return true if two chart item ID's are equivalent. The function is used whenever a chart value is being looked up from its item ID, to test whether each ID is the one that is sought.

The default value is equal, which should suffice for ordinary types of chart item ID's such as symbols, numbers, and strings. If all of the ID's are symbols, for example, then it may improve efficiency a bit to specify eq as the value of this property.

Chart item IDs are established by calls to set-chart-value or by a chart-value-returner function.

See also chart-object-id-equality-test.

See chart-widget and also cg-chart-widget.html.


chart-items

Generic Function, cg package

Arguments: chart-widget

Returns the value of the chart-items property of a chart-widget. The value may be set at creation time by passing the :chart-items initarg, or any time later by calling (setf chart-items).

This property contains a tree of values that are displayed in a chart-widget. This tree is normally built indirectly by successive calls to set-chart-value. Values are looked up here when the chart is being drawn, or when an application calls chart-value.

An application normally does not need to access this property directly, though it could build the tree of values itself and call (setf chart-items) to set all of the values at once. Here is an example of a chart-items value:

((:values #((:value 164) (:value 152 :low-value 148) (:value 103))
  :id (2005 dec 12))
 (:values #((:value 168) nil (:value 145 :icon-size 6))
  :id (2006 feb 3))
 ...)

The value is a list where each element of the list represents one chart item. An element for one chart item is a property list that can contain an :id entry for the chart item's ID and/or a :values item that contains a sequence of values. The value sequence may be either a list or a vector. Each element of the value sequence is a property list that holds the values for one chart object at this chart item. This property list can contain entries for any of the allowed types of values (see set-chart-value).

In the example above, the first chart item species a value of 164 for the first chart object, a value of 152 and a low-value of 148 for the second chart object, and so on. The second chart item specifies nil as a placeholder for the second chart object (which has no value at this chart item) so that it can specify a value for the third chart object.

To avoid building this tree of values at all, use a chart-value-returner function instead.

See chart-widget and also .


chart-items-length

Generic Function, cg package

Arguments: chart-widget

Returns the value of the chart-items-length property of a chart-widget. The value is the number of chart items that a chart-widget currently has, as a result of calling set-chart-value to add each item. Reading this cached value is more efficient than calling length on the chart-items property. An application should never set the value of this property.

See also chart-items-pushed-off.

See chart-widget and also cg-chart-widget.html.


chart-items-limit

Generic Function, cg package

Arguments: chart-widget

Returns the value of the chart-items-limit property of a chart-widget. The value may be set at creation time by passing the :chart-items-limit initarg, or any time later by calling (setf chart-items-limit).

chart-items-limit is the maximum number of chart items that a chart-widget will collect. The value should be a positive integer, or else nil for no limit. The default value is nil.

If set-chart-value is called with an item index that would cause the number of chart items to exceed this limit, then older chart items are first removed to avoid exceeding the limit when the new item is added. ("Older" chart items means items with the lowest indices.)

This property would typically be used when collecting data incrementally over time, to cause a chart-widget to display the most recent N pieces of data while throwing away older data for efficiency.

To temporarily exclude older items from view rather than permanently removing them, use chart-items-min-index.

See also chart-items-pushed-off.

See chart-widget and also .


chart-items-max-index

Generic Function, cg package

Arguments: chart-widget

Returns the value of the chart-items-max-index property of a chart-widget. The value may be set at creation time by passing the :chart-items-max-index initarg, or any time later by calling (setf chart-items-max-index).

chart-items-max-index is the index of the last chart item of a chart-widget that should be displayed at the current time. The value should be a non-negative integer, or else nil for no maximum. The default value is nil.

If set-chart-value has been used to add items to the chart, then any item whose index is greater than this property value (if it is a number) will not appear in the chart. When the property value is nil, then no items are excluded. This property can be used to display only a subset of collected values that are of interest at the moment.

If instead a chart-value-returner function is used for looking up chart data, then this property should always be set to a non-negative integer to tell the chart the maximum item index that it should pass to the chart-value-returner function. Otherwise the chart-widget has no way of knowing how many items your function is prepared to return. (The property will arbitrarily default to 100 in this case, though that would usually not match the available data.)

This property is the maximum index that will be included, rather than the number of indeces to include. So for a chart-value-returner function to cover all values from a 100-element vector, for example, the value of this property should be 99 rather than 100.

See also chart-items-min-index.

See chart-widget and also cg-chart-widget.html.


chart-items-min-index

Generic Function, cg package

Arguments: chart-widget

Returns the value of the chart-items-min-index property of a chart-widget. The value may be set at creation time by passing the :chart-items-min-index initarg, or any time later by calling (setf chart-items-min-index).

chart-items-min-index is the index of the first chart item of a chart-widget that should be displayed at the current time. The value should be a non-negative integer, or else nil to effectively default to zero. The default value is nil.

If set-chart-value has been used to add items to the chart, then any item whose index is less than this property value (if it is a number) will not appear in the chart. When the property value is nil or zero, then no items are excluded. This property can be used to display only a subset of collected values that are of interest at the moment.

If instead a chart-value-returner function is used for looking up chart data, then this property could be used if your function handles a range of item indeces that does not begin at zero.

To permanently remove older items rather than temporarily excluding them from view, use chart-items-limit.

See also chart-items-max-index.

See chart-widget and also .


chart-items-pushed-off

Generic Function, cg package

Arguments: chart-widget

Returns the value of the chart-items-pushed-off property of a chart-widget.

chart-items-pushed-off is the number of chart items that have been discarded from a chart-widget by the chart-items-limit property. This will be zero if the chart-items-limit property has not been used to discard any items.

The total number of items that have been collected so far could be found by adding this value to the chart-items-length property. An application should never set the value of this property.

See chart-widget and also cg-chart-widget.html.


chart-legend

Generic Function, cg package

Arguments: chart-or-plot

Returns the value of the chart-legend property of a chart-or-plot. The value may be set at creation time by passing the :chart-legend initarg, or any time later by calling (setf chart-legend).

A chart-legend is the table at the bottom of a chart-or-plot that shows a label for each chart object and indicates which line or set of bars in the chart display that object's values. The value is an instance of the chart-legend class.

The value of this property is always a chart-legend. If you do not pass a chart-legend instance as the value of the :chart-legend initarg when creating a chart-or-plot, then a default instance is created automatically.

See chart-or-plot, plot-widget, chart-widget and also .


chart-object-id-equality-test

Generic Function, cg package

Arguments: chart-or-plot

Returns the value of the chart-object-id-equality-test property of a chart-or-plot. The value may be set at creation time by passing the :chart-object-id-equality-test initarg, or any time later by calling (setf chart-object-id-equality-test).

The value of this property is a function (or the name of a function) that should return true if two chart object ID's are equivalent. The function is used whenever a chart value is being looked up from its object ID, to test whether each ID is the one that is sought.

The default value is equal, which should suffice for all ordinary types of chart object ID's such as symbols, numbers, and strings. If all of the ID's are symbols, for example, then it may improve efficiency a bit to specify eq as the value of this property.

Chart object IDs are established by the chart-objects property.

See also chart-item-id-equality-test.

See chart-widget, plot-widget, and also cg-chart-widget.html.


chart-objects

Generic Function, cg package

Arguments: chart-or-plot

Returns the value of the chart-objects property of a chart-or-plot. (Despite the word "chart" in the symbol name, this property applies similarly to a chart-widget or a plot-widget.) The value may be set at creation time by passing a chart-objects initarg to make-instance, or any time later by calling (setf chart-objects).

The chart-objects property can be used to specify several attributes of the objects that are displayed in a chart-or-plot. A "chart object" is represented by one of the lines of a multi-line line graph in a chart-widget, for example, or by one of the segments in each bar of a stacked bar graph (also in a chart-widget), or by a group of points that are drawn with a particular icon in a plot-widget. If a chart or plot displays only a single object, then there may be no reason to specify this chart-objects property.

The description of each object can include attributes such as its object-id (an arbitrary identifier), a label to display in the legend, whether to associate the object with a primary or secondary value-axis, and/or whether to currently exclude the object from the chart or plot.

The chart-objects value is a sequence (a vector or list) where each element represents one chart object. The first element of the sequence is said to have an object-index of 0, the second element an object-index of 1, and so on. The element for each object is a property list of keywords and values. Here are the keys that may be used in the plist for an object:

If the chart-objects property is replaced with a different vector or list, then the chart-or-plot will be updated automatically to reflect the new value. But if you modify the existing vector or list, then the widget will not know that anything has changed, and so you would need to call update-chart-widget explicitly to update the display.

Here is a sample chart-objects value that might display bowling scores in a chart-widget for Doris and Hubert, overlaid with the room temperature for each bowling event. Explicit legend labels are supplied so that no on-print-chart-object function needs to be written. The bowling scores will default to being displayed along the scale of the primary value axis, while the temperatures will use the scale of a secondary value axis. Hubert will (for now) be excluded from the chart.

#((:id :doris :label "Doris")
  (:id :hubert :label "Hubert" :exclude t)
  (:id :temperature :label "Temperature" :value-axis 2))

See chart-widget, plot-widget, and also .


chart-orientation

Generic Function, cg package

Arguments: chart-widget

Returns the value of the chart-orientation property of a chart-widget. The value may be set at creation time by passing the :chart-orientation initarg, or any time later by calling (setf chart-orientation).

chart-orientation is a value that specifies whether the value axis of a chart-widget is oriented vertically or horizontally. The value should be one of the keywords :vertical or :horizontal. The default value is :vertical, for the typical case where a chart's value-axis is vertical and its data items are laid out along a horizontal item-axis.

The values of each axis may also be ordered in either direction; see invert-axis.

See chart-widget and also cg-chart-widget.html.


chart-value

Function, cg package

Arguments: chart-widget &key item-index object-index item-id object-id (value-type :value)

Returns an individual value that is in a chart-widget. This could be a value that was added by calling set-chart-value or a value that's returned by the widget's chart-value-returner function if it has one. The value will be nil if the chart does not contain a value for the specified item, object, and value-type, and otherwise it will be a number.

chart-widget is the widget to be accessed.

The keyword arguments are:

See chart-widget and also .


chart-value-returner

Generic Function, cg package

Arguments: chart-widget

The value of this property can be a function (or the name of a function) that supplies the data values to be displayed in a chart-widget. Otherwise it should be nil (the default), in which case the chart's data must be supplied by calling set-chart-value multiple times. chart-widget must be a chart-widget.

The function will be called automatically every time the chart-widget draws a value. The arguments to the function indicate which chart item and object it is drawing, and which type of value. The function should return a number to display (or an item ID; see below), or else nil if that type of value should not be drawn at all.

Generally when using a chart-value-returner you should also specify the chart-items-max-index property of the chart-widget, and maybe also the chart-items-min-index property, to tell the chart the range of item indices that it should pass to the function. And if the chart contains more than one object, then you should also set up the chart-objects property to tell the chart the range of object indices that it should pass to the function (and typically their object IDs as well).

Note that in the inspector this property is on the Events tab because its value is a function, though it is not actually handling window system events.

See the page for the chart-widget class for an example of a chart-value-returner function, or the chart-widget tutorial (in cg-chart-widget.html for further examples.

The parameter list of a chart-value-returner function should be this:

Arguments: chart-widget value-type item-index object-index object-id

These arguments are:

See chart-widget and also .


chart-view

Generic Function, cg package

Arguments: chart-widget

Returns the value of the chart-view property of a chart-widget. The value may be set at creation time by passing the :chart-view initarg, or any time later by calling (setf chart-view).

This property indicates the type of chart to draw. The value may be :bar to draw a bar chart, or :line to draw a line graph. The default value is :line.

The same data are used for either view, though values of types :high-value and :low-value are used only by the bar chart view, and values of type :icon-size are used only by the line graph view. (See set-chart-value and chart-value-returner for information on the various types of data values.)

When the value is :bar, then the bar-chart-view instance in the bar-chart-view property is used to draw a bar chart. When the value is :line, then the line-graph-view instance in the line-graph-view property is used to draw a line graph instead.

See chart-widget and also cg-chart-widget.html.


check-fixnums

Function, cg package

This function is no longer supported. The behavior of the following code is similar to the old behavior of this function:

(defun my-check-fixnum (&rest args)
  (dolist (i args)
    (if (null (excl:fixnump i)) 
        (error "Non fixnum ~S passed to my-check-fixnum" i))))

checkable

Generic Function, cg package

Arguments: menu-item

This menu-item property is no longer used. It was related to the GTK version of CG, which is no longer supported.


checked

Generic Function, cg package

Arguments: list-view-item

This property has an effect only on the Windows platform, where it is provided by the underlying Microsoft control.

Returns the value of the checked property of a list-view-item of a list-view control. The value may be set at creation time by passing the :checked initarg to make-instance, or any time later by calling (setf checked).

This property specifies whether a list-view-item on a list-view control is currently checked. This can be true only if the show-check-boxes property of the list-view is true to show the special column of check boxes. The default value is nil.

Typically an application would call checked on various list-view-items of a list-view control once the user has exited the dialog that contains the list-view, to see which items the user has checked. An application can also call (setf checked) on a list-view-item to set whether that item is checked or unchecked.

The generic function (setf checked) will also be called whenever the end user interactively toggles the checked state of an item by clicking on it. An application could add an :after method to catch whenever the checked state changes, though it is more typical to give the list-view control an on-check function, which will be called when the state of any of its check boxes has changed.


checked-pixmap

Generic Function, cg package

Arguments: menu-item

This menu-item property is implemented only on the Windows platform.

Returns the pixmap, if there is one, that was specified to be displayed on the left side of the menu-item when the menu-item is checked (meaning when it's selected property is true). If no such pixmap was specified, then nil is returned.

The pixmap can be specified by passing a checked-pixmap initarg when calling make-instance to create the menu-item. The value should be either a pixmap or nil, and the default is nil. The value would be used only if the menu-item's checkable property is true.

If a menu-item's checkable and selected properties are both true but the checked-pixmap property is nil, then a default check mark pixmap is displayed.

See also unchecked-pixmap.


child-p

Generic Function, cg package

Arguments: basic-pane

Returns true if basic-pane is not a top-level window; that is, if it has a non-owner parent window, not counting the screen.


choose-default-printer

Function, cg package

Arguments:

This function displays a dialog containing the list of installed Windows printers. If you select a printer from this dialog and click OK, then Allegro CL modifies the win.ini file to make the chosen printer the current default printer for all Windows applications (just as if you selected it using the Windows Control Panel). Allegro CL will now use that printer as well.


class-info

Generic Function, cg package

Arguments: class-or-name

This symbol is exported only because it can be included in code that is generated for an object-editor form or a class-grid on a form. It should not be used by applications.


clear-cached-cell-value

Generic Function, cg package

Arguments: grid-row grid-column &key (row-number 0) (column-number 0)

Removes the cached value (if any) for the grid cell that is defined by the intersection of grid-row (which must be a grid-row) and row-number with grid-column (which must be a grid-column) and column-number. Also calls invalidate-cell to cause the cell to be redrawn, reading a possibly updated application value to display. See cache-cell-values.


clear-cached-cell-values

Generic Function, cg package

Arguments: grid-widget

Removes the cached values for all cells of grid-widget (which must be a grid-widget). Also calls invalidate on grid-widget to cause it to be redrawn with possibly updated application values. See cache-cell-values.


clear-delayed-cell-value

Generic Function, cg package

Arguments: row column &key (row-number 0) (column-number 0)

Clears the delayed interactive edit that is being held for a particular cell of a grid-widget (if any), and then calls invalidate-cell to redraw the cell with its previous values. An application might call this function if the user indicates that they made a mistake while editing a particular cell, if the grid is using the delay-write-cell-value option. Call clear-delayed-cell-values instead to clear the delayed values of all of the grid's cells at once.


clear-delayed-cell-values

Generic Function, cg package

Arguments: grid-widget

Clears all delayed interactive edits that are being held by grid-widget (which must be a grid-widget), and then calls invalidate on grid-widget to redraw it with the previous values. An application typically would call this function just after it asks the user to confirm or reject current edits to the grid, and the user rejects them. See delay-write-cell-value and clear-delayed-cell-value.


clear-focus

Generic Function, cg package

Arguments: window

This generic function is called whenever a window loses the keyboard focus. Applications may add :after methods in order to be notified when this occurs. An application should not call clear-focus itself, and the built-in methods should not be overridden. See also set-focus.


clear-grid-section

Generic Function, cg package

Arguments: grid-widget row-section column-section drawing-pane section-box

clear-grid-section is called internally whenever all or part of a grid-section (of a grid-widget) is redisplayed. For efficiency, it is called a single time to draw the empty background of an entire section before draw-cell is called for each of the individual visible cells of the section. The default method simply calls erase-contents-box to clear the section.

An application should not call this function, but may add methods to override the default method if desired. One case where this may be useful is to reduce flashing that may occur for example if clicking and dragging in a cell produces an animation effect by repeatedly changing the domain value represented by the cell and invalidating the cell to redraw it at each stage. If the draw-cell methods for all of the cells in the grid-section are written to draw the entire contents of the cells, then clear-grid-section need not do anything and so a method that does nothing could be added to eliminate the flashing caused by the default method clearing the background.

The arguments are:

See also draw-cell, draw-grid-section, draw-grid and grid-widget.


clear-named-gradient

Generic Function, cg package

Arguments: graphical-stream

Causes the current named gradient, if any, to no longer be in effect. This simply sets the variables that were set by set-named-gradient back to nil, and the stream argument is ignored.

Typically you would use the macro with-named-gradient instead of this function.

graphical-stream is the Common Graphic stream on which filling was done using the gradient.

This generic function is implemented only on Windows and JavaScript/HTML.

See also named-gradient.


clear-page

Function, cg package

Arguments: &optional stream

Resets the contents of the argument stream to the background texture that initially filled the stream. The function is useful for clearing windows. Changes to the background-color or background-texture often do not take effect until clear-page is called. stream should be a cg-stream.

If stream is a text-edit-pane, clear-page removes all text in the pane.


clear-template

Function, cg package

Arguments: editable-text

Sets the string of a editable-text control editable-text back to the empty version of its template. See template-string.


click-event

Generic Function, cg package

Arguments: dialog widget

click-event is called automatically whenever the user left-clicks on a control that implements the click event. The default method calls the on-click event-handler function of the control if it has one.

Click behavior could be specified for a whole control subclass by defining a click-event method for that subclass rather than giving the same on-click event-handler function to every instance of the subclass.


click-must-be-on-gadget

Generic Function, cg package

Arguments: grid-column

This is a property of the classes check-box-column-mixin and combo-box-column-mixin, which implement pseudo-controls in grid-widget columns. When set to true, the user must click on the small gadget within the cell in order to activate it by clicking. When nil, the user can click anywhere in the interior of the cell. (Pressing the spacebar or return key will still activate the gadget regardless of the value of this property.)

The default is true. The advantage of having this property on is that the user can click in the cell to simply give it the keyboard focus, without changing the value or showing a list of choices. The disadvantage is that the clickable area is smaller.


click-off

Generic Function, cg package

Arguments: standard-object

Returns the value of the click-off property for its argument. This property determines whether a button can be un-pressed by clicking it when it looks pressed in.

This property applies to button controls that remain depressed after clicking them. Sometimes it is desirable to allow your users to un-press the button by clicking a second time, while other times it is desirable to require some other action such as clicking another button in the same cluster or within the same multi-picture-button.

Here are the possible values and their effects:

click-off is a property of the multi-picture-button, picture-button, and radio-button classes.


click-position

Generic Function, cg package

Arguments: cursor

Returns (or sets with setf) a position object that determines what point within the mouse cursor image will register as the clicked position when the mouse is clicked. With an arrow cursor, for example, the click-position would be expected to be at the pixel that defines the very tip of the arrow. A position with coordinates (0,0) indicates the upper left corner of the image.

The argument must be a mouse cursor instance.


click-to-toggle-inclusion

Generic Function, cg package

Arguments: chart-legend

Returns the value of the click-to-toggle-inclusion property of a chart-legend. The value may be set at creation time by passing a click-to-toggle-inclusion initarg to make-instance, or any time later by calling (setf click-to-toggle-inclusion).

If true, then the end user can interactively toggle whether particular chart objects are currently included in the chart-widget or plot-widget by clicking on the labels for the objects in the legend. An object's label will be grayed in the legend when it is excluded. The default value is nil because users typically will not expect this behavior.

An application could implement side effects when an object is toggled on or off by supplying an exclude-or-include-chart-object method.

See the description of the :exclude key on the page for chart-objects.


clipboard

Generic Function, cg package

This function has been removed in the 7.0 release. In earlier releases, it returned the Lisp clipboard object. That object is now the value of the variable *clipboard*.


clipboard-changed

Generic Function, cg package

Arguments: clipboard-format

This generic function is called whenever the contents of the Lisp clipboard stack changes. An application could add a method to this generic function to catch whenever this happens.

The Lisp clipboard and the Windows clipboard usually change at the same time when functions such as push-lisp-clipboard, pop-lisp-clipboard, copy-command, and cut-command are called, but if the function (setf clipboard-object) is called directly to change the Windows clipboard, then the Lisp clipboard is not changed and clipboard-changed is not called.

The argument is the current value of *clipboard*, reflecting the new state. This value is a list of conses, where the car of each cons is an object on the clipboard and the cdr is one of the symbols :text, :rich-text, or :pixmap indicating the Windows clipboard format of that object. The default method does nothing, so an application could simply replace it with a primary method specializing on t, or add an :after method specializing on t.

See cg-clipboard.html.


clipboard-format-from-object

Generic Function, cg package

Arguments: *object *

Returns a keyword symbol that indicates which clipboard format of the underlying platform's system-wide clipboard is suitable for the specified data object. The returned value may be useful for passing to push-lisp-clipboard or (setf clipboard-object).

The default methods return :pixmap for a pixmap and :text for anything else. The other possible format, :rich-text, is never returned because that would require parsing a string to see if it is a valid rich text string, and guessing that it is intended to be pasted as one.

See cg-clipboard.html.


clipboard-history-limit

Generic Function, cg package

Arguments: configuration

Returns or sets with setf the maximum number of cut or copied objects that the clipboard will hold. (Once this number of items are on the clipboard, adding another will remove the oldest item.) clipboard-history-limit is a property of the configuration class.

See cg-clipboard.html.


clipboard-object

Generic Function, cg package

Arguments: clipboard-format

This generic function returns (or sets with setf) the value of the system clipboard for a specified format. The argument may be either :text, :rich-text, or :pixmap to indicate the format. On Windows, other custom locations can also be specified as clipbord-format values. See the Windows Note below.

CG/JS Note: The :rich-text format is not supported. And the :pixmap format works only within a CG application, and not system-wide.

When using the setf, the value should match the specified format, where :text indicates a regular Lisp string, :rich-text indicates a regular Lisp string that happens to be in rich text format (such as can be retrieved by calling rich-edit-range on a rich-edit widget or rich-edit-pane), and :pixmap indicates a Common Graphics pixmap object. (Common Graphics uses the "device-independent bitmap" Windows clipboard format to pass pixmaps on the Windows clipboard to and from other applications.)

The setf of this function has an additional keyword parameter called empty-clipboard, which defaults to t. When true, this causes the clipboard to be completely cleared before placing the new value onto the clipboard. This ensures that no values of other data formats are left on the clipboard along with the new value. If it is desired to place data of multiple formats onto the clipboard, then specify this argument as nil when adding successive formats, as in:

(setf (clipboard-object :text :empty-clipboard nil) "foo")

Note that the setf of this function does not modify the Lisp clipboard stack. To modify both the system clipboard and the Lisp clipboard stack, use a function such as push-lisp-clipboard or copy-command rather than (setf clipboard-object).

See cg-clipboard.html.

The older functions clipboard-string and clipboard-pixmap are deprecated in favor of this newer single function.

Windows File Explorer note: On Windows, the argument may also be the keyword :file-list. If the most recent copy that was done (system-wide) was copying a set of files in the Windows File Explorer, then this will return a list of the full path namestrings of those files. Otherwise this will return nil. Calling paste-command will retrieve and use this special value if it is there (which should be OK because the Windows clipboard apparently never holds both a :text value and a :file-list value at the same time).

Windows Note

It is possible to place text at alternate "locations" on the Windows system clipboard, by simply passing the clipboard-format argument as any symbol other than the standard :text, :rich-text, or :pixmap. This is probably useful only if you have multiple standalone Lisp applications, or multiple running instances of a single application, where they are all aware of the same location names. Then one instance could place text at various locations, and another instance could read the text at whichever locations it is interested in.

Here's an example, where typically one Lisp application instance would do the first pair of calls, and a second instance might do the second pair of calls, but it works in a single Lisp as well.

(setf (clipboard-object :text) "primary text")
RETURNS "primary text"

(setf (clipboard-object :place-two :empty-clipboard nil) "secondary")
RETURNS "secondary"

(clipboard-object :text)
RETURNS "primary text"

(clipboard-object :place-two)
RETURNS "secondary"

clipboard-pixmap

Function, cg package

Arguments:

This function is deprecated. Use clipboard-object instead.

clipboard-pixmap creates a Common Graphics pixmap object from the device-independent bitmap (DIB) that is currently on the Windows clipboard, and returns it. (If there is no DIB currently on the clipboard, then nil is returned instead.) This allows a Common Graphics application to retrieve and use a pixmap that was placed ("copied") onto the clipboard by another application.

The setf function, (setf clipboard-pixmap) places a Common Graphics pixmap onto the Windows clipboard as the current device-independent bitmap (DIB), ready for other applications to "paste" it or otherwise retrieve it.

pixmap is the pixmap to "copy" to the Windows clipboard.

Example:

(setf (clipboard-pixmap) my-pixmap)

See cg-clipboard.html.


clipboard-string

Function, cg package

Arguments: clipboard-format

This function is deprecated. Use clipboard-object instead.

The function returns a lisp string for the current Windows clipboard object. clipboard-format may be either :text or :rich-text.

The setf function sets the current Windows clipboard value for clipboard-format to a specified value.
clipboard-format currently must be either :text or :rich-text. value currently must be a either a plain-text or rich-text string, according to value of clipboard-format.

See cg-rich-text.html for information on rich text editing in Common Graphics. See also cg-clipboard.html.


clipping-box

Function, cg package

Arguments: stream

This function and the related nclipping-box returns two values. The first is a box representing the current clipping box of stream relative to the current origin. stream should be a cg-stream but may not be a text-edit-window or a text-edit-pane.

The second returned value, which is one of the symbols :simple, :complex, or nil, indicates which type of clipping region the window currently has. :simple means that box returned as the first value exactly describes the clipping region. :complex means that the box encompasses a non-rectangular clipping region; Common Graphics does not provide any further information about this region however. nil means that the clipping region is empty (of size zero) and so nothing can be drawn on the stream currently; in this case the first return value is the box (0 0 0 0), though the arbitrary "position" of this box at (0 0) is not meaningful.

Note that the box returned (as the first value) is not merely the value that may have been set by a call to (setf clipping-box) or with-clipping-box; it also reflects how the window is partly or fully covered by other windows and how it is scrolled. Specifically, the returned box is the smallest box containing the currently visible parts of the window's interior (in stream units), intersected with the box most recently specified by a call to (setf clipping-box) or with-clipping-box, if any. A window whose interior is completely covered will always return the box (0 0 0 0) and a second value of nil to indicate a currently empty clipping region.

An application may call (setf clipping-box) at any time to set the current clipping-box of a Common Graphics stream. The value argument may be either a box to establish clipping, or else nil to remove all clipping. The macro with-clipping-box is a handy alternative because it guarrantees that the original clipping-box will be restored after its body executes.

While the function (setf clipping-box) and the macro with-clipping-box are often useful for establishing a clipping region, applications generally are not expected to have a need to call clipping-box or nclipping-box to retrieve the current region. The functions are not reliable for recalling the region that was explicitly set, since the returned box is also affected by how the window is covered. Furthermore, all drawing code for a window (other than a bitmap-pane) normally should be placed within a redisplay-window method, which always receives a box argument denoting the area that needs to be redisplayed, and the clipping-box of the window is set to this box automatically during the call to redisplay-window.

Platform note: the box that is returned will exclude any part of the window that happens to be covered by other windows on the Microsoft Windows platform.


close-button

Generic Function, cg package

Arguments: basic-pane

Returns true if basic-pane has an active close button (a control on the title bar which closes the window when clicked) and nil otherwise. When nil, a close button appears but it is unavailable (grayed out).

The close-button property may not be changed on an existing window, and must instead be specified with the inspector when designing a window (using a form) or with the :close-button initarg of make-window. (It can be changed using the inspector when designing a form but not for a running window or control, either in the IDE or in an application.)


close-dde

Function, cg package

The symbol naming this operator has been moved to the dde package. Please see close-dde.


close-image-list

Generic Function, cg package

Arguments: image-list

Closes an image-list so that it is no longer usable unless it is re-opened by calling open-image-list. It is not expected that applications will normally need to call this function, but it may be useful to call this for image-lists which are not currently needed in order to save space or Windows resources if a large number of image-lists are used over time.

Common Graphics will automatically re-open a closed image-list whenever it is assigned to a list-view control, such as by calling (setf small-image-list). But care should be taken never to close an image-list which is currently in use by a list-view control. See the description of the list-view control.

See list-view.


close-menu-and-submenus

Function, cg package

Arguments: menu

Closes the specified menu and all of its descendent cascading submenus, by recursively calling the standard Common Lisp function close on each one. CG does not do this automatically because it allows adding a menu as a child of multiple parent menus.

Closing menus is likely only needed in rare cases to avoid depleting limited resources of the underlying Windowing system, in particular the Microsoft Windows limit of 32,767 total menu-items in an application.

See also close-window-and-menus.


close-outline-item-value

Generic Function, cg package

Arguments: outline item-value &optional no-redisplay-p

Causes the subitems of the outline-item of outline whose value is item-value to be hidden.

Alternately, (setf state) may be called to change the state of an outline-item. This may by more efficient if you have the outline-item object in hand, rather than its value only. See the description under the heading State on outline-items near the bottom of the page for state.


close-palette

Generic Function, cg package

Arguments: stream palette

Destroys palette, releasing any operating system storage. palette must not be the palette of any open stream.

stream is for discrimination purposes only; (screen *system*) (see screen and *system*) may normally be used. If a stream, stream should be a cg-stream.


close-pixmap-handle

Generic Function, cg package

Arguments: pixmap

Tells the operating system to destroy its device-dependent pixmap resource that it is using for a pixmap object, and sets the pixmap-handle of the pixmap object to nil. After this is done, the pixmap can still be used, but will be drawn by sending the array of pixels to the operating system each time rather than passing only the handle of the operating system's internal version of the pixmap.

open-pixmap-handle can be called again later to create a new device-dependent pixmap if desired. This function does nothing if the pixmap object already has no handle. Calling this function may be useful to save operating system pixmap resources (though a handle is not created and given to the pixmap object to begin with unless open-pixmap-handle is called to do this).


close-port

Function, cg package

The symbol naming this operator has been moved to the dde package. Please see close-port.


close-server

Function, cg package

The symbol naming this operator has been moved to the dde package. Please see close-server.


close-subtrees-on-close

Generic Function, cg package

Arguments: outline

Returns (or sets with setf) the value of this property of outline. This property determines whether all descendent outline-items of an outline-item that is being closed are also closed.

When true, closing and then re-opening an outline-item results in the item's subitems reappearing without any of their subitems reappearing, even if they were visible before closing the outline-item. When false, closing and reopening an outline-item results in the tree of subitems reappearing just as it was before the outline-item was closed. (The Windows File Explorer works as if this property were false. Suppose some folders in the C drive have subfolders that are displayed. Clicking on the boxed - next to the C drive icon renders all folders in C invisible but when you then click on the boxed + next to the C drive icon, the folders reappear and those folders that were open before are open again.)

The value of this property defaults to t for backward compatibility, but may be set to nil to achieve behavior similar to the Windows File Explorer.

close-subtrees-on-close is a property of the outline class.


close-window-and-menus

Function, cg package

Arguments: window

Closes the specified window, and also calls close-menu-and-submenus on the menu-bar of the window, if it has one.


closed-pixmap

Generic Function, cg package

Arguments: outline-pixmap-interface

Returns the pixmap instance used to indicate a non-expanded outline item. closed-pixmap is a property of the outline-item, outline, and dropping-outline classes.


closed-pixmap-name

Generic Function, cg package

Arguments: outline-pixmap-interface

Returns (or sets with setf) the symbol name of the pixmap instance to display on non-expanded outline-items. When setting this value, the pixmap that is set should have been placed into the set of cached pixmaps at some point by calling cache-pixmap on it.

closed-pixmap-name is a property of the outline-item, outline, and dropping-outline classes.


closed-pixmap-source

Generic Function, cg package

Arguments: outline-pixmap-interface

Returns (or sets with setf) the path namestring of the .bmp pixmap file from which the pixmap instance to display on non-expanded outline-items was originally read (if any). When this value is set, load-pixmap is called on the path namestring, a pixmap object is created from the information that is read, and the pixmap is cached by calling cache-pixmap on it so that it may later be retrieved by calling find-pixmap on its name.

closed-pixmap-source is a property of the outline-item, outline, and dropping-outline classes.


cluster

Generic Function, cg package

Arguments: windows-button

Returns the value of the cluster property of windows-button. This property groups picture-button or radio-button controls into clusters (and also menu-items, see below). If a user clicks one button in the cluster, that button will be turned on and all other buttons in the cluster turned off.

Clusters are logical associations independent of physical placement on the dialog, but controls must be on the same dialog to be in the same cluster. All of the buttons in a single cluster will have an identical Lisp symbol (such as :cluster-1 or :send-form-button-panel) in their cluster property. The controls are also often arranged visually as a group, perhaps in a group-box.

The cluster property can also be used with menu-items. A set of contiguous menu-items can act like a set of radio-buttons, where calling (setf selected) to mark one of the menu-items as selected automatically deselects all of the other menu-items in the group. The group is set up by setting the cluster property of each menu-item in the group to the same arbitrary symbol, just as with radio-button widgets. In addition, a menu-item whose cluster property is non-nil will be marked by a small round dot when selected rather than with a check mark. It is a good idea to place a menu-separator between the menu-items in a cluster and any other menu-items on the same menu to clarify to the end user which items are in the group.

In the following example, each time (pop-up-menu my-menu) is called and a menu-item is selected, the menu's on-click function toggles whether that item is selected, which is apparent only when the menu is shown a further time. The "Independent" item is not in a cluster, while the other two items are in a cluster named :a. Selecting one of the items in the cluster will unselect the other item in the cluster if it was selected, but will not unselect the "Independent" item if it was selected.

(defparameter my-menu nil)

(setq my-menu
  (open-menu (list (make-instance 'menu-item
                     :title "Independent")
                   menu-separator
                   (make-instance 'menu-item
                     :title "One"
                     :cluster :a)
                   (make-instance 'menu-item
                     :title "The Other"
                     :cluster :a))
             'pop-up-menu
             (screen *system*)
             :on-click #'(lambda (menu menu-item stream)
                           (declare (ignore menu stream))
                           (setf (selected menu-item)
                             (not (selected menu-item)))
                           (title menu-item))))

(pop-up-menu my-menu) ;; call this multiple times

cluster is a property of the picture-button, radio-button, and menu-item classes.


color

Generic Function, cg package

Arguments: hotspot-or-text-edit-pane

Hotspot: when the argument is a hotspot, returns (or sets with setf) the color in which to draw a hotspot.

Text-edit-pane: for a text-edit-pane, color returns two values: (1) an rgb object for the color of the first character in the selected range of text-edit-pane (or the character at the cursor), and (2) true if and only if the whole selection is the same color.

Again, for a text-edit-pane, (setf color) sets the color of the selected range of the argument text-edit-pane to new-value, which should be an rgb object (see make-rgb).

A text-edit-pane argument must be an instance of a text-edit-pane (which is a superclass of rich-edit-pane). It cannot be a text-edit-window or a rich-edit control (apply window to a rich-edit control to get a value suitable as an argument to this function).

See cg-rich-text.html for information about rich text editing in Common Graphics.


color-for-characters

Generic Function, cg package

Arguments: cg-configuration

Returns the color that is used by colorize-source-code for literal characters, or nil to avoid colorizing literal characters at all.

The value may be set by calling (setf color-for-characters). The value should be an RGB color, as created with make-rgb, or nil. This option also appears on the Editor Color tab on the Options dialog.

Example

(setf (color-for-characters (configuration *system*))
      (make-rgb :red 0 :green 120 :blue 160))

color-for-comments

Generic Function, cg package

Arguments: cg-configuration

Returns the color that is used by colorize-source-code for comments (including block comments), or nil to avoid colorizing comments at all. This is probably the most useful type of source code colorization, to visually offset comments from actual code. Options for other types of colorization could be set to nil if they result in too much overall color.

The value may be set by calling (setf color-for-comments). The value should be an RGB color, as created with make-rgb, or nil. This option also appears on the Editor Color tab on the Options dialog.

Example

(setf (color-for-comments (configuration *system*))
      (make-rgb :red 0 :green 120 :blue 160))

color-for-external-allegro-symbols

Generic Function, cg package

Arguments: cg-configuration

Returns the color that is used by colorize-source-code for symbols that are external in Allegro packages other than the common-lisp, cg, and ide packages, or nil to avoid colorizing these symbols at all. This color may be useful for warning when you have mistyped an Allegro symbol, or to remind you that a particular function is built into Allegro rather than being defined by your application.

The colorization is based only on the symbol's package and external status, and will occur even where the symbol is not being used as the function or variable for which it is exported.

The value may be set by calling (setf color-for-external-allegro-symbols). The value should be an RGB color, as created with make-rgb, or nil. This option also appears on the Editor Color tab on the Options dialog.

Example

(setf (color-for-external-allegro-symbols (configuration *system*))
      (make-rgb :red 0 :green 120 :blue 160))

color-for-external-cg-symbols

Generic Function, cg package

Returns the color that is used by colorize-source-code for symbols that are external in the cg and ide packages, or nil to avoid colorizing these symbols at all. This color may be useful for warning when you have mistyped a Common Graphics symbol, or to remind you that a particular function is a Common Graphics function rather than one of your own.

The colorization is based only on the symbol's package and external status, and will occur even where the symbol is not being used as the function or variable for which it is exported.

The value may be set by calling (setf color-for-external-cg-symbols). The value should be an RGB color, as created with make-rgb, or nil. This option also appears on the Editor Color tab on the Options dialog.

Example

(setf (color-for-external-cg-symbols (configuration *system*))
      (make-rgb :red 0 :green 120 :blue 160))

color-for-external-cl-symbols

Generic Function, cg package

Arguments: cg-configuration

Returns the color that is used by colorize-source-code for symbols that are external in the common-lisp package, or nil to avoid colorizing these symbols at all. This color may be useful for warning when you are about to inadvertently redefine a standard Common Lisp symbol, or when you have mistyped one.

The colorization is based only on the symbol's package and external status, and will occur even where the symbol is not being used as the function or variable for which it is exported.

The value may be set by calling (setf color-for-external-cl-symbols). The value should be an RGB color, as created with make-rgb, or nil. This option also appears on the Editor Color tab on the Options dialog.

Example

(setf (color-for-external-cl-symbols (configuration *system*))
      (make-rgb :red 0 :green 120 :blue 160))

color-for-global-variables

Generic Function, cg package

Arguments: cg-configuration

Returns the color that is used by colorize-source-code for global variables and constants, or nil to avoid colorizing global variables and constants at all. Specifically, this applies to symbols for which boundp is true when the colorization is done.

The value may be set by calling (setf color-for-global-variables). The value should be an RGB color, as created with make-rgb, or nil. This option also appears on the Editor Color tab on the Options dialog.

Example

(setf (color-for-global-variables (configuration *system*))
      (make-rgb :red 0 :green 120 :blue 160))

color-for-strings

Generic Function, cg package

Arguments: cg-configuration

Returns the color that is used by colorize-source-code for literal strings, or nil to avoid colorizing literal strings at all. This may be especially useful for very long strings, to make the boundaries of the strings more apparent.

The value may be set by calling (setf color-for-strings). The value should be an RGB color, as created with make-rgb, or nil. This option also appears on the Editor Color tab on the Options dialog.

Example

(setf (color-for-strings (configuration *system*))
      (make-rgb :red 0 :green 120 :blue 160))

color-for-user-functions

Generic Function, cg package

Arguments: cg-configuration

Returns the color that is used by colorize-source-code for function name symbols in non-allegro packages, or nil to avoid colorizing these symbols at all. Specifically, this applies to symbols for which fboundp returns true when the colorization is done, and whose home packages are not packages that are built into Allegro. This may be useful for determining when you have mistyped the name of a function that is defined by your application.

The value may be set by calling (setf color-for-user-functions). The value should be an RGB color, as created with make-rgb, or nil. This option also appears on the Editor Color tab on the Options dialog.

Example

(setf (color-for-user-functions (configuration *system*))
      (make-rgb :red 0 :green 120 :blue 160))

color-number

Generic Function, cg package

Arguments: stream rgb

Converts rgb into a color-number. The nearest matching color in stream's palette is returned. Returns nil if stream's palette is :rgb. See cg-color-palettes.html.


color-string-at-cursor

Generic Function, cg package

Arguments: rich-edit-pane

Calls color-string-at-index on rich-edit-pane, passing the current text cursor position as the index argument. The current text cursor position may be found with

(cl:file-position rich-edit-pane)

The returned string will be the one around the text cursor which is in the color of the character just before the text cursor. The color is returned as a second value, as with color-string-at-index.

See cg-rich-text.html for information about rich text editing in Common Graphics.


color-string-at-index

Generic Function, cg package

Arguments: rich-edit-pane index

Returns two values:

(1) the string that surrounds the character at index in rich-edit-pane and which is in the color of the rich-edit-pane at that position (in other words, the color of the character just before the index position).

(2) the color of the string as an RGB color object.

If the text just before index is black, then it is assumed that the cursor is not in a special color string, and nil is returned immediately to avoid searching through a lot of non-color text. Otherwise the two values mentioned above will be returned.

See cg-rich-text.html for information about rich text editing in Common Graphics.


color-under-mouse

Generic Function, cg package

Arguments: split-bar

Returns the color-under-mouse property of a split-bar widget. The value may be set at creation time by passing the :color-under-mouse initarg to make-instance, or any time later by call (setf color-under-mouse).

This is the color of the split-bar widget when it is under the mouse cursor but it is not being dragged.

The value may be either an RGB color object (see make-rgb), or a constant symbol or global variable whose value is an RGB, or nil to use the system-edge-shadow-color, or else t to match the parent window's background color, making the split-bar invisible. The value may be set at creation time by passing the :color-under-mouse initarg to make-instance, or any time later by call (setf color-under-mouse).

The default value is t to avoid distracting the user with a split-bar that flashes whenever the mouse happens to move over it. The changing mouse cursor indicates that a drag can be done there, even when the split-bar itself cannot be seen.


color-when-dragging

Generic Function, cg package

Arguments: split-bar

Returns the color-when-dragging property of a split-bar widget. The value may be set at creation time by passing the :color-when-dragging initarg to make-instance, or any time later by call (setf color-when-dragging).

This is the color of the split-bar widget while the user is dragging it to a new position.

The value may be either an RGB color object (see make-rgb), or a constant symbol or global variable whose value is an RGB, or nil to use the system-edge-shadow-color, or else t to match the parent window's background color, making the split-bar invisible. The value may be set at creation time by passing the :color-when-dragging initarg to make-instance, or any time later by call (setf color-when-dragging).

The default value is nil to draw the split-bar in a default color, to help the user see exactly where they are placing the bar.


color-when-idle

Generic Function, cg package

Arguments: split-bar

Returns the color-when-idle property of a split-bar widget. The value may be set at creation time by passing the :color-when-idle initarg to make-instance, or any time later by call (setf color-when-idle).

This is the color of the split-bar widget when it is not being dragged and it is not under the mouse cursor.

The value may be either an RGB color object (see make-rgb), or a constant symbol or global variable whose value is an RGB, or nil to use the system-edge-shadow-color, or else t to match the parent window's background color, making the split-bar invisible. The value may be set at creation time by passing the :color-when-idle initarg to make-instance, or any time later by call (setf color-when-idle).

The default value is t to avoid distracting the user with an always-visible split-bar. The changing mouse cursor when the mouse moves over a split-bar indicates that a drag can be done there, even when the split-bar itself cannot be seen.

When changing this property from the default value of nil to something else, you will probably want to also change the color-under-mouse property, or else the split-bar would confusingly disappear when the user moves the mouse over it.

If drawing the split-bar as a simple colored line is not adequate, then an on-redisplay function could be supplied to draw the split-bar in a custom way.


colorize

Generic Function, cg package

Arguments: texture color-number-0 color-number-1 bits-per-pixel

Returns a pixel-map of pixels capable of holding palette-size colors made from texture by using color-number-0 for 0 and color-number-1 for 1.


colorize-on-load-file

Generic Function, cg package

Arguments: cg-configuration

Returns whether source code colorization will be done automatically whenever load-file is called on a lisp-edit-pane. In the IDE, load-file is called when a file is shown in the editor. Applications may call load-file as well.

This option appears on the Editor Color tab on the Options dialog in the IDE, and may also be set programmatically by calling (setf colorize-on-load-file). The initial value is nil because colorization adds a significant delay, especially for larger files. An alternative in the IDE is to colorize only on demand by using the Colorize Definition and Colorize Buffer commands on the Edit menu.

See also colorize-source-code.

Example

(setf (colorize-on-load-file (configuration *system*)) t)

colorize-on-typing

Generic Function, cg package

Arguments: cg-configuration

Returns whether source code colorization will be done automatically as editing is done in a lisp-edit-pane in which any colorization has been done already.

Specifically, a call to colorize-source-code will be made when the user types a space, closing parenthesis, or newline, as well as the first time the text cursor is moved without colorization having otherwise been done since the most recent text change.

This incremental colorization is usually very fast because it colorizes only the text between the character position where the text was changed and the beginning of the innermost s-expression that contains that character position. There may be a significant delay, though, when that character range is large.

This option appears on the Editor Color tab on the Options dialog in the IDE, and may also be set programmatically by calling (setf colorize-on-typing). The initial value is t, though it still does not do anything unless colorization has already been done in the lisp-edit-pane by some other means.

Example

(setf (colorize-on-typing (configuration *system*)) t)

Warning

When this option is enabled, the Edit | Undo command will not work as expected just after typing has triggered an automatic recolorization. The reason is that the Undo command uses functionality that is built into the text-editing control that is supplied by the underlying window system, and this control cannot distinguish a change that was made by typing from a change that Common Graphics made as part of colorization. You could avoid this problem by using only the colorize-on-load-file option and/or the Colorize Definition and Colorize Buffer commands on the Edit.


colorize-source-code

Generic Function, cg package

Arguments: lisp-edit-pane &key entire-buffer levels skip-preroll skip-invalidation from-position

Colorizes some or all of the text in a lisp-edit-pane. This is intended for use with Common Lisp source code, and results with other sorts of text would be rather arbitrary. The purpose is to visually distinguish various elements of source code so that programmers may more easily spot what they are looking for, and also to make typos more apparent. This function is used (optionally) by the IDE editor, and an application that handles source code could call this function as well.

This function may be called explicitly, and is also called automatically if either of the configuration options colorize-on-load-file or colorize-on-typing are enabled. Other configuration options control what types of elements are colorized and which color to use for each type; these options are:

The IDE never saves colorization into the file that is written from an editor buffer.

lisp-edit-pane should be the lisp-edit-pane to colorize.

If entire-buffer and levels are both nil (as they are by default), then the top-level definition that surrounds the current text cursor position (or from-position if specified) is colorized. If entire-buffer is true, then all of the text in the lisp-edit-pane is colorized. Otherwise, if levels is true then it should be a positive integer that indicates how many s-expressions outward to colorize backward from the current text cursor position (or from-position if specified). For example, if levels is 2 (and entire-buffer and from-position are nil), then the colorization will be done from the beginning of the s-expression that surrounds the s-expression that surrounds the current text cursor position, to the current text cursor position.

skip-preroll is used internally and is not intended for use by applications.

If skip-invalidation is nil, as it is by default, then the part of the lisp-edit-pane that may have changed is invalidated at the end so that it is redrawn to reveal any new colors. If it is true then no invaildation is done. Generally, true should be specified only if you know that the window will be redrawn later by some other means; this may avoid flashing caused by multiple redisplays, since the text control may redraw itself immediately when invalidated rather than waiting until no more events are queued as most windows do.

If from-position is nil, as it is by default, then the colorization is based on the current text cursor position. Otherwise it should be a character index (a non-negative integer) indicating the position on which to base the colorization.


colors

Generic Function, cg package

Arguments: pixmap

Returns (or sets with setf) the vector of colors that are used to draw the pixels of the pixmap. This actually just accesses the texture-info-colors of the texture-info of the pixmap object, where the texture-info is kept as a sub-object for backward compatibility.

The value of this property can be the symbol :default as well as a vector of colors. This special value means to use the colors currently returned by default-pixmap-color-vector. If the colors used in the pixmap are equivalent to those returned by initial-pixmap-color-vector (and in the same order), then it may be desirable to specify :default. The reason is that Common Graphics replaces three of the colors in the default-pixmap-color-vector with colors that match the end user's color scheme (as specified in the Windows Control Panel). Specifying :default will ensure that the pixmap uses those three special colors in the end user's scheme. Specifically, the color at index 7 will be the value returned by system-dialog-background-color, position 8 will hold the system-edge-shadow-color, and position 15 (the last position) will hold the system-background-color.

colors is a property of the pixmap class.


column-click

Generic Function, cg package

Arguments: list-view column

A generic function that is called internally when the end user clicks on the header of a list-view-column. The default method sorts the list-view by the contents of the clicked column, but an application could override or add to this sorting functionality by defining additional column-click methods. See the description of the list-view control.


column-header-cells

Generic Function, cg package

Arguments: grid-widget

Returns a list that contains the header-cell child object of every grid-column in every column-section of grid-widget (a grid-widget). The properties of each of these objects can be modified to specifically modify the drawing style of the header cell of each column.

This function is mainly for use when creating a grid-widget on a form window and modifying its properties (like this one) interactively in the inspector (see cg-grid-widget-simplified-tutorial.html). But it can be called programmatically at run time as well.


column-header-defaults

Generic Function, cg package

Arguments: grid-widget

Returns an object that specifies default drawing style properties for the header-cell of each grid-column of grid-widget (a grid-widget). Setting a property value of this object will set the same property value of the header-cell of each existing column in each column-section of grid-widget to the specified value. Thereafter, the header-cell of any columns that are added to a column-section by calling (setf subsection-count) will get initial property values from this object as well.

The values of this object's properties can be the same as the values of the same properties of grid rows and columns. They can also be the special keyword symbol :defer, which means that the header cell should use the same value for that property as the other cells in that row or column. The values are initially :defer for each property, allowing you to override only the particular properties that should differ for the header cells only.

Typically you might want the font to be bold only in all column header cells. This would be the place to specify a bold font to make that happen.

This function is mainly for use when creating a grid-widget on a form window and modifying its properties (like this one) interactively in the inspector (see cg-grid-widget-simplified-tutorial.html). But it can be called programmatically at run time as well.


column-header-font

Generic Function, cg package

Arguments: class-grid

Returns the font that is used in the header cell at the top of each grid-column of a class-grid. The value may be set with the column-header-font initarg or by calling (setf column-header-font).


column-header-height

Generic Function, cg package

Arguments: class-grid

Returns the section-size (height in pixels) of the row of column header cells at the top of a class-grid. The value may be set with the column-header-height initarg or by calling (setf column-header-height).

A larger value will cause column header strings to wrap to multiple lines, sometimes allowing a smaller column width to be used.


column-label-margin

Generic Function, cg package

Arguments: lamp

A property of the lamp widget. This generic function returns the number of blank pixels between the array of images in a lamp widget and the label strings above or below the columns. The value may be specified at creation time with the column-label-margin initarg, or anytime later by calling (setf column-label-margin). This value is used only when the value property of the lamp widget is an array.


column-label-offset

Generic Function, cg package

Arguments: lamp

A property of the lamp widget. This generic function returns the number of blank pixels by which to shift the label strings rightward above or below the columns of images in a lamp widget. The value may be specified at creation time with the column-label-offset initarg, or anytime later by calling (setf column-label-offset). This value is used only when the value property of the lamp widget is an array.

This property may be used as a fudge factor to make the labels appear as aligned as possible with the lamp images, adjusting for the internal leading of the widget's font.


column-label-orientation

Generic Function, cg package

Arguments: lamp

A property of the lamp widget. This generic function returns whether the label strings that are above or below the columns of images in a lamp widget are drawn vertically of horizontally. The value may be one of the keyword symbols :vertical or :horizontal. The value may be specified at creation time with the column-label-orientation initarg, or anytime later by calling (setf column-label-orientation). This value is used only when the value property of the lamp widget is an array.

Generally :horizontal is a good choice when the strings are short enough (such as a single letter) to fit horizontally above or below each column. Otherwise :vertical would be needed, though :vertical amkes the labels a bit harder to read.


column-label-side

Generic Function, cg package

Arguments: lamp

A property of the lamp widget. This generic function returns the side on which the column-labels of a lamp widget are displayed. The value may be one of the keyword symbols :top or :bottom. The value may be specified at creation time with the :column-label-side initarg, or anytime later by calling (setf column-label-side). This value is used only when the value property of the lamp widget is an array.


column-labels

Generic Function, cg package

Arguments: lamp

A property of the lamp widget. This generic function returns a list of strings to display above or below the columns of images in a lamp widget. The value may be specified at creation time with the column-labels initarg, or anytime later by calling (setf column-labels). This value is used only when the value property of the lamp widget is an array.

The first string is displayed on the leftmost column of images, the second string on the next column, and so on until there are no more columns or strings. The strings are displayed on the column-label-side of the lamp images, with column-label-margin blank pixels in between.


column-padding

Generic Function, cg package

Arguments: calendar-widget

The number of extra blank pixels to add between adjacent columns in a calendar widget.

See also the calendar class and the function ask-user-for-date.


column-section

Function, cg package

Arguments: grid-widget section-name

Returns a column-section object given its name and the grid that it is on.

See the grid-widget class for an overview of writing grid-widget code.


column-sections

Generic Function, cg package

Arguments: grid-widget

The list, from left to right, of a grid-widget's grid-column-sections. Each grid-column-section is a set of columns that (optionally) can be scrolled horizontally. The section of columns is clipped at some arbitrary width, and the width of the column section can (optionally) be changed by clicking on and horizontally dragging the vertical border on the right side of the section.

column-sections is a property of the grid-widget class.


column-width

Generic Function, cg package

Arguments: item-list

This function is specific to Windows, and returns nil on other platforms.

Returns the width of each column in pixels on single-item-list and multi-item-list controls. The value nil is arbitrarily interpreted as a width of 150 pixels. There is no maximum width. This value is used only if the multi-column-p property is true.

The :column-width initarg will set the column width initially, and the setf of this function may be called (on Windows only) to change the column width any time later.


columns

Generic Function, cg package

Arguments: list-view

Returns (or sets with setf) the list of list-view-columns of a list-view control.

columns is a property of the list-view class.


command-buttons

Generic Function, cg package

Arguments: object-editor

Returns a list of the standard command buttons that are included on object-editor, which must be an object-editor. The value may be set at creation time with the command-buttons initarg, or any time later by calling (setf command-buttons).

The value should be a list containing any subset of the keyword symbols in the left column below. The list of all choices is the value the constant *object-editor-command-buttons*, which is the default value of this property. Each button calls an exported generic function, which is shown to the right of the button name here. An application could add custom widgets that call these functions rather than using the built-in buttons. An application could also add wrapper methods to the generic functions to intercept all usage of the command buttons (or other calls to the functions). See the doc pages for the functions for more information on the behavior of these buttons.

Button Name

Generic Function Called

Notes

:first-button

display-special-instance

(passing :first)

:previous-button

display-special-instance

(passing :previous)

:next-button

display-special-instance

(passing :next)

:last-button

display-special-instance

(passing :last)

:select-button

object-editor-select

:search-button

object-editor-search

:save-button

object-editor-save

:revert-button

object-editor-revert

:new-button

object-editor-new

:delete-button

object-editor-delete

:commit-button

cg-commit

:rollback-button

cg-rollback

The order of the buttons in this property value does not make a difference because the buttons that are included are automatically layed out in certain standard positions. When creating an object-editor interactively as a form window in a project, you could move the buttons to wherever you like after the automatic layout is done.

:save-button is a default-button, and so pressing the Enter key in an object-editor will call object-editor-save (unless the keyboard focus is on some other button widget, which makes that button be the acting default button). :revert-button is a cancel-button, and so pressing the Escape key anywhere in an object-editor will call object-editor-revert.

:commit-button and :rollback-button ordinarily should not be used on an object-editor whose edited-class is not a persistent class.


command-line

Generic Function, cg package

Arguments: app

Returns as a string the value of the command-line property of app. When app is (app *system*) (see app and *system*), the command-line used to start the current Lisp invocation is returned.

command-line is a property of the app class.


common-graphics-implementation-version

Function, cg package

Arguments:

Returns as a string the version identifier of the currently running implementation of Common Graphics. Please include this information in any problem report or question about the product.


common-status-bar-p

Generic Function, cg package

Arguments: window

Returns true if the argument is an instance of the common-status-bar class and returns nil otherwise.


compile-unsaved-form

Function, cg package

This function is no longer supported.


component

Generic Function, cg package

Arguments: window

Returns the dialog-item associated with window if there is one, and otherwise returns window itself.

Similar to the function dialog-item, except that dialog-item returns nil rather than the window itself when there is no associated dialog-item.


comtab

Generic Function, cg package

Arguments: comtab-mixin

Returns (or sets with setf) the comtab of a window (comtab-mixin is a mixin class which is a superclass of window classes that have comtabs, such as text-edit-pane). A comtab is conceptually a table of commands (keystrokes and chords) associated with a window. A chord is a combination of keys pressed simultaneously, such as Control-A and Escape-W.

The function set-event-function modifies the current comtab. See the description of that function for examples involving comtabs.


concatenate-rich-text

Function, cg package

Arguments: &rest rich-text-strings

Concatenates an arbitrary number of rich-text strings into a single rich-text string.

Note that simple concatenation (such as with concatenate) does not work with rich-text strings because each string has a header that defines fonts and so on, and also because a later string could inherit formatting from the end of the previous string. This function merges the headers and current formatting of the multiple strings as needed. If all of the arguments are either the null string or nil, then nil is returned.


configuration

Generic Function, cg package

Arguments: system

Returns the configuration associated with the argument system. The current system is the value of *system* so the current configuration is the value of (configuration *system*). The configuration is a data structure holding values for many configurable aspects of the working environment, such as the values of global variables.

All of the configuration options may be edited in the inspector by using the Tools | Inspect System Data | Configuration Options menu command. Most of them appear on the Tools | Options dialog as well, in a friendlier format. A configuration option may also be changed programmatically by setf'ing the option, which is a property of the configuration object, for example, displaying of tooltips can be disabled with the form

(setf (show-tooltips (configuration *system*)) nil)

(See show-tooltips.) All configuration options are saved in the allegro-ide-options.cl when the Tools menu | Save Options Now menu command is used, or when the IDE is exited if the Tools menu | Save Options on Exit is enabled (as it is by default). If this file is deleted or renamed, then all configuration options will revert to their defaults in the next Lisp session. See The user options file allegro-ide-options.cl in cgide.html for more information on the options file.

configuration is a property of the system class.


configure-gestures

Generic Function, cg package

Arguments: window &key pan pan-with-single-finger-vertically pan-with-single-finger-horizontally pan-with-gutter pan-with-inertia two-finger-tap zoom rotate press-and-tap

Establishes which capabilities of the gesture interface will be enabled for the specified window. The value of each keyword argument can be either t to enable the capability, nil or unspecified to disable it, or :inherit to inherit the value from an ancestor window or else the system defaults. Since unspecified values disable the associated capabilities, all capabilities that are to be enabled need to be passed on any call to this function.

Here are the meanings of the keyword arguments, all of which appear to be enabled by default (at least on the test machine) except where otherwise noted:

See also the touch-point class and About Touch Gesture Support in Common Graphics on Windows in cgide.html.


confirm-grid-subsection-deletion

Generic Function, cg package

Arguments: grid-widget selected-subsections

This generic function is called when the user presses the delete key while a grid-widget has the keyboard focus, and whenever delete-selected-subsections is called with a true confirm argument (as it is by the delete key). Its purpose is to ask the user whether to proceed with deleting any deletable rows or columns that are selected. An application should not call this function, but may override the default method in order to customize the manner in which the user is asked for confirmation, or even to suppress the delete key behavior altogether.

grid-widget is the grid-widget that has the keyboard focus when the delete key is pressed. selected-subsections is a list of any grid-rows and grid-columns of the grid that are both deletable and selected. The method should return true if all of the selected-subsections should be deleted, and nil if not.

The default method shows a warning dialog if selected-subsections is the empty list, and otherwise shows a modal dialog with a generic message asking the user whether to proceed with the deletion. Here is the default method:

(defmethod confirm-grid-subsection-deletion ((grid-widget grid-widget)
                                             selected-subsections)
  (if* selected-subsections
     then (y-or-n-dialog "Delete rows and / or columns ~a ?"
                         (mapcar #'name selected-subsections))
     else (pop-up-message-dialog
           (window grid-widget) "Nothing to Delete"
           "There are no selected and deletable rows or columns to delete."
           warning-icon "~OK")
          nil))

All interactive deletion could be suppressed (even if rows and columns are selectable for other purposes) by simply always returning nil from this function.

The calling of this generic function is never suppressed by adding custom cell-key-down methods. It could be suppressed by overriding the default virtual-key-down method for the grid-drawing-pane of the window of the grid-widget, though this would be modifying the keypress behavior of the grid at a low level.

See also select-subsection, deselect-subsection, and deletable.


confirm-web-browser-exit

Function, cg package

Arguments:

Returns whether the web browser will prompt the user for exit confirmation when they attempt to close the web browser tab or reload the page. The setf of this function can be called at run time to establish whether the web browser will do that for the rest of the current session. The default value is nil. Setting it to true can avoid losing unsaved changes in the CG app. This function has an effect only in CG/JS mode.

The default value for the generated application of a project can be set with the Confirm Exit widget in the CG/JS tab of the Project Manager in the IDE. The default value for the IDE can be set with the query-web-browser-exit IDE option. Those defaults can be overridden at startup time with the --confirm-exit command line argument.

(setf (confirm-web-browser-exit) t)   ;; avoid losing changes

conserve-indentation

Generic Function, cg package

Arguments: configuration

Returns the value of the conserve-indentation property of configuration. The current configuration is the value of (configuration *system*) (see configuration and *system*).

If the value of this property is true, the indentation style (of Lisp code entered in an Editor buffer) will be closer in style to the style used in Emacs generally (but not in the IDE Emacs editor mode). Note that exceptions can be made for individual operators in the IDE editor by calling (setf text-edit-indentation) on the desired operators. Note that operators whose names begin with strings such as "with-", "do-", and "def-" indent more closely regardless of the value of this property.

When this property is nil, arguments on successive lines will be left-justified with a first argument that is on the same line as its operator, unless an indentation style has been established for the particular operator with a call to (setf text-edit-indentation) or the operator begins with certain strings such as "with-", "do-", or "def" that always indent more closely. This default matches indentation in the Emacs editor. Setting this property to true causes successive lines to always indent more closely.

The value of this property may be set with setf with a form like

(setf (conserve-indentation (configuration *system*)) [new-value])

The value can also be set by checking the appropriate box on the Editor of the Options dialog.


console-handle

Function, cg package

Arguments:

This function exists only on the Windows platform.

Returns the handle of the Allegro console window if it exists, and otherwise returns nil. The console window is not a Common Graphics window, but Windows API functions could be called directly on this handle if desired.

(The console will not exist if the +c command line argument has been specified, such as in a project's standalone application when the "Enable Debugging of Runtime Errors" option has been turned off on the Build tab of the Project Manager dialog. Command line options are listed in Command line arguments in startup.html.)


console-is-visible

Function, cg package

Arguments:

This function exists only on the Windows platform.

Returns true if the Allegro CL console window exists and is currently visible, and otherwise returns nil.

(The console will not exist if the +c command line argument has been specified, such as in a project's standalone application when the "Enable Debugging of Runtime Errors" option has been turned off on the Build tab of the Project Manager dialog. Command line options are listed in Command line arguments in startup.html.)


console-title

Function, cg package

Arguments:

This function exists only on the Windows platform.

Returns the string that is currently displayed in the Allegro console window's title-bar, if the console window exists, and otherwise returns nil.

The setf of this function may be called to change the console's title. The value must be a string. Nothing will be done if the console window does not exist.

(The console will not exist if the +c command line argument has been specified, such as in a project's standalone application when the "Enable Debugging of Runtime Errors" option has been turned off on the Build tab of the Project Manager dialog. Command line options are listed in Command line arguments in startup.html.)

Example

(setf (console-title) "Console for Debugging")

console-tray-icon

Function, cg package

Arguments:

This function exists only on the Windows platform.

Returns the handle (an integer) for the icon that is currently displayed in the system tray for the Allegro CL console window, if the console window exists and it has a tray icon, and returns nil otherwise. (setf console-tray-icon) may be called to change the icon displayed in the tray.

(The console will not exist if the +c command line argument has been specified, such as in a project's standalone application when the "Enable Debugging of Runtime Errors" option has been turned off on the Build tab of the Project Manager dialog. Command line options are listed in Command line arguments in startup.html.)

Example

(setf (console-tray-icon) application-icon)

See application-icon.


console-tray-tooltip

Function, cg package

Arguments:

This function exists only on the Windows platform.

If the Allegro CL console window exists and it has a tray icon and the tray icon's tooltip value has been set by a call to (setf console-tray-tooltip), then console-tray-tooltip will return that value, and otherwise it returns nil. (The default tooltip that was initially embedded is not known.)

(setf console-tray-tooltip) may be called to change the tooltip of the console's tray icon. The value may be a string to display or else nil to remove the tooltip entirely. Nothing is done if the console window does not exist.

(The console will not exist if the +c command line argument has been specified, such as in a project's standalone application when the "Enable Debugging of Runtime Errors" option has been turned off on the Build tab of the Project Manager dialog. Command line options are listed in Command line arguments in startup.html.)


contents

Generic Function, cg package

Arguments: texture

Returns a value that specifies the pixels that form the image of a pixmap. The value may be set either by calling (setf contents) or by passing the :contents initarg to make-instance when creating the pixmap.

pixmap should be a pixmap object. See cg-pixmaps.html for an overview of pixmap functionality.

The value returned by contents or passed to (setf contents) is a list of lists, where each inner list represents a row of the pixmap and each member of an inner list represents a pixel in that row. Each row member should be an index into the pixmap's colors vector, to make the pixel display the color at that index. (An exception is that if the pixmap has a mask, then any transparent pixels should be zero in the contents.)

The number of inner lists reflects the number of rows in the pixmap, and the number of members in each inner list (these should all be the same) reflect the number of columns. The width, height, and bits-per-pixel properties of a pixmap will be derived automatically from the contents if needed.

The pixels of a pixmap may alternately be specified either by specifying the texture property.

Example

Here is how the :default-leaf pixmap (used by outline widgets) is created. This pixmap also uses the default colors from default-pixmap-color-vector.

(cache-pixmap
 (make-instance 'pixmap
   :name :default-leaf
   :contents
   '((15 15 15 15 15 15 15 15 15 15 15 15 15 15 15 15)
     (15 15  0  0  0  0  0  0  0 15 15 15 15 15 15 15)
     (15 15  0 15 15 15 15 15  0  0 15 15 15 15 15 15)
     (15 15  0 15 15 15 15 15  0 15  0 15 15 15 15 15)
     (15 15  0 15 15 15 15 15  0 15 15  0 15 15 15 15)
     (15 15  0 15 15 15 15 15  0 15 15 15  0 15 15 15)
     (15 15  0 15 15 15 15 15  0  0  0  0  0  0 15 15)
     (15 15  0 15 15 15 15 15 15 15 15 15 15  0 15 15)
     (15 15  0 15 15 15 15 15 15 15 15 15 15  0 15 15)
     (15 15  0 15 15 15 15 15 15 15 15 15 15  0 15 15)
     (15 15  0 15 15 15 15 15 15 15 15 15 15  0 15 15)
     (15 15  0 15 15 15 15 15 15 15 15 15 15  0 15 15)
     (15 15  0 15 15 15 15 15 15 15 15 15 15  0 15 15)
     (15 15  0 15 15 15 15 15 15 15 15 15 15  0 15 15)
     (15 15  0  0  0  0  0  0  0  0  0  0  0  0 15 15)
     (15 15 15 15 15 15 15 15 15 15 15 15 15 15 15 15))))

control-or-command-key

Generic Function, cg package

Arguments: &optional return-symbol-value

Returns meta-key when the user is on a Mac or control-key otherwise. In CG, the symbol meta-key refers to the Command key on a Mac. If return-symbol-value is true then the symbol's value is returned, and otherwise the symbol itself is returned.

In CG/JS mode, the returned value reflects the platform where the web browser is running, rather than where the CG lisp application is running, which may be different when the CG app is running in server mode.

This function may be convenient when defining the event-synonym of a menu-item, when the Command key is used on a Mac and the Control key on Windows and Linux, and that is the only difference. For example:

   (make-instance 'menu-item
     :value 'paste-command
     :title "~Paste"
     :event-synonym (list (control-or-command-key) #\V))

contents-ref

Generic Function, cg package

Arguments: texture x y

Returns (or sets with setf) the value of the pixel at row x and column y of a texture or a pixmap. The pixel at zero, zero is the top-left pixel.

As noted, contents-ref is setf'able. It is recommended that you use setf and contents-ref rather than contents-set.


contents-set

Generic Function, cg package

Arguments: texture x y value

Sets the value of the pixel at row x and column y of a texture or a pixmap. The pixel at zero, zero is the top-left pixel.

Note that the related contents-ref is setf'able. It is recommended that you use setf and contents-ref rather than this function.


context-sensitive-help

Generic Function, cg package

Arguments: owner-window dialog-item-or-window

This generic function is called whenever the user presses the F1 key, typically to receive context-sensitive help. It is also called if the user clicks the question mark button on the title-bar of a window that has been given the help-button property, and then clicks a dialog-item or child window in the window that has the question mark button. An application can add context-sensitive-help methods in order to handle these gestures and present help to the user.

The built-in Common Graphics methods do nothing, though the Tools | Options dialog in the IDE has the help-button property and implements a context-sensitive-help method to show HTML help on the configuration option represented by the selected widget.

When F1 is pressed, owner-window will be the owner window or screen of the window that currently has the keyboard focus. If the focus is in a dialog-item's widget-window or lisp-widget-window, then dialog-item-or-window will be that dialog-item object (rather than its window); otherwise dialog-item-or-window will be the actual child window that has the keyboard focus.

When the question mark button is used instead, owner-window will be the owner window or screen of the dialog-item or child window on which the user clicks. If the user clicks on a dialog-item of the window that has the question mark button, then dialog-item-or-window will be that dialog-item object (rather than its window); otherwise dialog-item-or-window will be the actual child window that the user clicks. (After clicking the question mark button, if the user then clicks somewhere other than on a dialog-item or child window of the window that has the question mark button, or presses the Escape key, then the operation is cancelled and context-sensitive-help is not called.)

The owner-window is intended to be useful for specialization, so that the individual dialog-items or child windows do not all need to be subclassed.

If the F1 key is also handled as an event-synonym of a menu-item, or is handled by a virtual-key-down method, or is a global keyboard accelerator (see add-global-keyboard-accelerator), then that behavior is done in addition to context-sensitive-help being called, rather than one overriding the other.

Due to operating system design, it is unfortunately not possible to tell which action the user performed (either pressing F1 or using the question mark button).

Also due to operating system design, it is not possible to use the help-button property along with the minimize-button or maximize-button property; if both are specified or defaulted, the window will show the help button but will not be given the minimize or maximize buttons.

See cg-application-help.html for various ways of displaying help in an application.


convert-clipboard-from-lisp

Generic Function, cg package

Arguments: window top-item format

Use of this function is deprecated. Use (setf clipboard-object) instead.

Copies top-item to the Windows clipboard directly, without affecting the Lisp clipboard stack. window should be (development-main-window \*system\*). format in theory allows you to specify the format of the object being placed, but only text format is supported in this release, so format should simple be t.

See cg-clipboard.html.


convert-clipboard-to-lisp

Generic Function, cg package

Arguments: window

Use of this function is deprecated. Use clipboard-object instead.

Returns the text value from the Windows clipboard directly, without affecting the Lisp clipboard stack. window should be (development-main-window \*system\*).

See cg-clipboard.html.


convert-returned-dde-buffer

Generic Function, cg package

The symbol naming this operator has been moved to the dde package. Please see convert-returned-dde-buffer.


convert-returned-dde-string

Generic Function, cg package

The symbol naming this operator has been moved to the dde package. Please see convert-returned-dde-string.


copy-box

Function, cg package

Arguments: box

Returns a copy of box. Boxes are created with make-box.


copy-character-format

Generic Function, cg package

Arguments: window

Sets the global variable *copied-character-format* to a character-format instance reflecting the character format of the character just before the current text cursor position in window. window must be an instance of a text-edit-pane (which is a superclass of rich-edit-pane). It cannot be a text-edit-window or a rich-edit control (apply window to a rich-edit control to get a value suitable as an argument to this function).

The Edit | Copy Format command on the rich edit menubar calls this function. (Note: that command does not appear on the Allegro CL Edit menu.)

See cg-rich-text.html for information about rich text editing in Common Graphics.


copy-command

Generic Function, cg package

Arguments: window-or-widget

Retrieves an object from the specified window or widget and places it onto the clipboard. Returns the object that was copied and its clipboard format as two values, or the single value nil if no copy was done.

This is largely a convenience function that combines other exported functionality as it is typically used. An application menu command could call this function directly.

window-or-widget should an instance of the basic-pane, dialog-item or screen class or one of their subclasses.

The default copy-command and cut-command methods are shown below, in case you need to use some variation of this typical behavior. These methods first pass the action down to the bottom-most selected-window of the window that was passed in. Then they call either copy-selection or cut-selection to retrieve the object from the window or widget, and then call push-lisp-clipboard to add the object to the lisp clipboard (a stack of arbitrary lisp objects) as well as the system-wide clipboard of the underlying window system.

(defmethod copy-command ((stream cg-stream))
  (let* ((child (selected-window stream)))
    (if* child
       then (copy-command child)
       else (copy-or-cut-command stream nil))))

(defmethod cut-command ((stream cg-stream))
  (let* ((child (selected-window stream)))
    (if* child
       then (cut-command child)
       else (copy-or-cut-command stream t))))

(defun copy-or-cut-command (stream cut?)
  (setq stream (or (dialog-item stream) stream))
  (let* ((object (if cut?
                     (cut-selection stream)
                   (copy-selection stream))))
    (and object
         (let* ((format (clipboard-format-from-object object)))
           (with-object-locale (stream)
             (push-lisp-clipboard format object))
           (values object format)))))

There are also methods on dialog-item that simply pass the action to the widget's window when the widget is on a parent window.

A subtle point about the above code: The function dialog-item is called on the window so that cut-selection or copy-selection is called on a widget before being called on its associated window. This allows an application to specialize added methods on a dialog-item subclass rather than on a widget-window subclass, which would require subclassing both classes and linking them with a widget-device method.

Also, clipboard-format-from-object is called to find the appropriate format for the copied object on the underlying windowing system's clipboard.

The call to with-object-locale would be needed only in unusual cases where an application uses different locales in different widgets.

See cg-clipboard.html.


copy-graphics-context

Generic Function, cg package

Arguments: stream &optional (result-context (make-graphics-context stream))

Returns a graphics-context object that stores the current drawing style options of stream. stream should be a cg-stream.

The graphics-context can later be given to the same or another stream to resume using the saved drawing style options. The specific values saved are foreground-color, background-color, font, line-width, line-dashing, line-end, line-join, line-texture, fill-texture, background-texture, current-position, and stream-origin.

If a graphics-context is passed as the result-context argument, then this object is filled in and returned. Otherwise a new graphics-context is created and returned. (You create a graphics context object with make-graphics-context. Pass the same stream to that function as was passed as the first argument to this function.)

See also set-graphics-context, graphics-context-p, and restoring-graphics-context.


copy-menu-item

Generic Function, cg package

Arguments: menu-item

Returns a copy of the argument menu-item. A specific menu-item can only be only placed on one menu so use this function to create copies of menu-items you want on more than one menu.


copy-pixels-to-stream

Generic Function, cg package

Arguments: stream texture texture-info to-box-or-position from-box-or-nil paint-operation

Implements the bit block transfer operation, generalized to pixels. Pixels from texture are copied onto stream using paint-operation to combine them with the existing ones. Note that the function copy-to-stream does much the same thing as this function and does not require the use of separate texture and texture-info objects.

from-box-or-nil is either a box object or nil. If it is a box, it is the box in texture from which copying occurs. If it is nil, then the whole pixmap is copied.

to-box-or-position is either a box object or a position object. If it is a box, it is the box in stream which is modified. If it is a position, then the pixmap is copied with its upper-left corner at that position without stretching the pixmap.

Thus, if from-box-or-nil is nil and to-box-or-position is a position, then the entire pixmap is drawn at the specified position without stretching it.

The box to be copied is intersected with the texture dimensions and stream clipping box and the resultant box is the set of pixels actually copied. If texture is a bitmap, 1's are copied as stream's foreground color, 0's as its background color. If texture-info is nil, one that matches the stream is used.

When the destination area (to-box-or-nil) is a box of a different size than the source bitmap, the copied area is stretched rather than clipped to make it fit the destination area. Clipping is performed when the source area (from-box-or-nil) is a box of a different size than the source bitmap.


copy-pixels-to-stream-from-file

Function, cg package

Arguments: filename &optional stream position

This function reads a pixmap file and copies the image to stream. stream should be a cg-stream. This function may be useful for displaying many large pixmaps without the overhead of creating lisp representations of each pixmap, since the pixels are transferred directly from the file to the stream without creating any lisp array to store them in. No pixmap object is created, so the individual pixels cannot be examined in lisp (except by calling pixel or pixel-x-y to ask the stream for its pixel values).

filename is a pathname or path namestring indicating the file to read the pixmap from. This file should be either a .bmp (device-independent bitmap), .ico (icon), or .cur (cursor) file.

stream is either a window, a bitmap-stream, a printer stream, or nil. It indicates the stream to draw the pixmap on. If nil, a bitmap-stream is created and used. If the pixmap is to be used in multiple places or at multiple times in the interface, it may be useful to call this function once to store the pixmap on a bitmap-stream, and then copy the image from there to a window with copy-stream-area whenever needed.

position is a position or nil, indicating where to position the upper left corner of the pixmap on stream. If nil, the image is positioned in the upper left corner of the stream.

Two values are returned:

  1. the stream that was passed in or created,

  2. a texture-info containing the dimensions, depth, and colors of the pixmap.

Note that if stream is a bitmap-pane, then the image is copied to the backing store of the window but not to the visible window itself. The image may then be viewed at any time by calling invalidate on the window. This allows loading a new pixmap into the window while the end user is still viewing the previous pixmap, and then to very quickly switch to the new pixmap when the user is ready.


copy-pixels-with-mask-to-stream

Function, cg package

Arguments: to-stream texture texture-info to-box-or-position from-box-or-nil mask-texture

This function is similar to copy-pixels-to-stream except it allows you to copy a non-rectangular image. This is done by passing a mask-texture. The texture defines which pixels should be copied and which should be left unchanged.

The first five arguments are the same as for copy-pixels-to-stream. The sixth argument is mask-bitmap, a 1-bit-per-pixel texture with a 1 wherever the texture should be transparent (destination is left alone) and a 0 wherever texture should modify the destination. This function works by erasing the destination wherever there is a 1 in mask-texture and then merging in texture with the paint operation. (Since the operation is predefined, there is no paint-operation argument.)

If you use load-pixmap to load a .ico (icon) file, the third returned value is a mask bitmap suitable for using as the mask-texture argument.


copy-position

Function, cg package

Arguments: pos

Returns a copy of the argument position.


copy-selection

Generic Function, cg package

Arguments: window-or-widget

Returns an object from the specified window or widget that is suitable for placing onto the clipboard, or nil if no suitable object is found. This function is called by copy-command, which does the actual placing of the object onto the clipboard. An application could call either function, or add methods to either in order to extend the clipboard functionality.

window-or-widget should be an instance of a basic-pane subclass or a dialog-item subclass.

If a copy was done, then a second value is returned that indicates the clipboard format that is appropriate for the copied object on the underlying platform's system-wide clipboard. This will be one of the keywords :text, :rich-text, or :pixmap. The Windows clipboard knows how to hold one value of each of its clipboard formats simultaneously.

The default method returns the object returned by calling selected-object, plus :text as the second value. The methods for bitmap-pane and drawable-pane return a pixmap that is created by calling get-pixmap on the window, plus :pixmap as the second value. The method for rich-edit-pane returns the selected text as a rich text string, plus :rich-text as the second value. The method for dialog-item simply calls copy-selection on the window of the dialog-item if the widget is currently on a parent window.

An anomaly: When called on a rich-edit-pane in Windows, it is copy-selection rather than copy-command that actually places the object onto the clipboard. This is due to a problem with mapping the Common Graphics behavior onto the Windows clipboard and rich-edit APIs. In this case, both the rich text string and the plain text string are placed onto the clipboard, with the rich text string being topmost on the lisp clipboard stack.

An application could add methods for additional widget or window classes if you would like to call copy-selection (or copy-command) on the selected widget or window without regard to its class, letting it handle the command if it knows how. To do this for a widget (rather than a window), you could specialize on the dialog-item subclass if you will only call copy-selection on the widget; if you might instead pass the widget's associated window, then you would need to specialize on the widget-window subclass. Doing so requires subclassing both the dialog-item class and the widget-window class, and associating the two subclasses together with a trivial widget-device method.

cut-selection does what this function does and also deletes the returned object from the window or widget. See also paste-selection.

Compatibility notes

In releases prior to 7.0, this function passed its action to the lowest selected descendent child window of the specified window, though some applications may not desire such automatic redirection. The functions focus-component, get-focus, or selected-window may be useful for finding a suitable widget or window to pass to this function. Earlier releases also returned the window where the copy was actually done as the first value, and the copied object as the second value.

See cg-clipboard.html.


copy-stream-area

Generic Function, cg package

Arguments: to-stream from-stream to-box from-box paint-operation

Like copy-pixels-to-stream but copies pixels from from-box of from-stream to to-box of to-stream. The texture used in copying is the fill texture of the to-stream. to-stream and from-stream should be cg-streams.


copy-to-stream

Generic Function, cg package

Arguments: pixmap-or-cursor stream &optional to-box-or-position from-box-or-nil (mode po-replace) alpha

Copies a pixmap object or a mouse cursor object to stream. stream should be a cg-stream. This function replaces the older function copy-pixels-to-stream, which required the use of separate texture and texture-info objects.

If from-box-or-nil is a box, this function copies the from-box-or-nil portion of pixmap-or-cursor to the to-box-or-position portion of stream, using a particular pixel-combination mode. If from-box-or-nil is nil, the whole pixmap or cursor is copied.

If to-box-or-position is a box, the pixmap-or-cursor is copied to that box and is stretched (if necessary) as with copy-pixels-to-stream. If to-box-or-position is a position, then the pixmap or cursor is copied without stretching so its upper left corner is at the position. If to-box-or-position is nil (the default), then the pixmap or cursor is copied without stretching to position 0,0 of stream.

If pixmap-or-cursor has a mask texture, then copy-pixels-with-mask-to-stream is called internally in order to use it. Otherwise copy-pixels-to-stream is called internally. If pixmap-or-cursor has a pixmap-handle, then that is used for drawing the pixmap, and otherwise the pixmap's texture is used.

mode may be any value that is valid as the paint-operation of a stream. copy-to-stream always uses the value of this mode argument, rather than using the stream's current paint-operation as other drawing functions do. The default value is po-replace. See paint-operation for more information on the various choices.

The alpha argument is used only on Windows, and only when the variable *alpha-blending* is true. It can create translucent effects where the existing background partly "shows through" the pixmap that is being displayed. Its value should be either nil or an integer between 0 and 255 inclusive. If 255, nil, or unspecified, the pixmap will be drawn with full opacity. Otherwise the value specifies the amount of opacity, where 0 would make the pixmap completely transparent and unseen (not useful), and where for example 192 would let the previous background show through by one-fourth. See the variable *alpha-blending* for more information.

Instead of passing a pixmap object, you can alternately pass either a cursor object, a pixmap handle, or a symbol that is bound to a pixmap, cursor, or pixmap handle. copy-to-stream will not work on a cursor object if calling texture on it returns nil, as is the case with several cursors supplied by the operating system, because Common Graphics does not have the pixel array to copy.

To fill an area by tiling a pixmap rather than by stretching it, call replicate-pixmap instead.

For an overview of pixmaps, see cg-pixmaps.html.


count-icons-in-file

Function, cg package

Arguments: filename

This function is specific to the Windows platform, and will always return 1 elsewhere. On other platforms, pixmaps can be used where icons are used on Windows.

Returns a non-negative integer indicating the number of icons in the file filename. Zero is returned if the file does not exist, is of some other type, or if no icons are in the file. filename should be a string indicating a file with a .ico, .dll, or .exe extension.

See cg-icons.html.


create-icon-handle

Function, cg package

Arguments: pixmap

This function is specific to the Windows platform, and will have no effect elsewhere. On other platforms, pixmaps can be used where icons are used on Windows.

Returns an icon handle, which can be used as the icon of a window's titlebar, or as the pixmap-icon property of controls that display pixmaps or passed to copy-to-stream or copy-pixels-to-stream. The pixmap object should contain a mask in addition to the usual texture.

An icon handle is like a pixmap handle (a handle to a device-dependent pixmap that resides in the OS) that has a mask built in, so that the background color or whatever was drawn before the icon can show through the icon.

See also extract-icon-from-file, for creating icons from Windows icon files rather than from Common Graphics pixmaps.

See cg-icons.html.


create-pixmap-handle

Generic Function, cg package

Arguments: stream texture texture-info

Creates a device-dependent pixmap and returns a handle to it. The pixmap will contain the correct colors for drawing on stream using stream's current palette. stream should be a cg-stream.

This function is largely for the backward compatible style of using separate objects for the texture, texture-info, and pixmap handle. It is now recommended to instead use a pixmap object, which encapsulates all of these. With a pixmap, call open-pixmap-handle to cause the pixmap to use a handle to a device-dependent pixmap rather than passing its array of pixels each time it is drawn.


creation-process

Generic Function, cg package

Arguments: basic-pane

Returns the Lisp process that called make-window to create the argument basic-pane (which is typically a window).

This function may be useful for managing windows in multiple processes, due to certain considerations that are good to keep in mind when multiple processes create windows. For example:

Miscrosoft Windows Note: Creating a single window hierarchy that contains windows created in multiple processes is likely to lead to messaging timeouts or hangs when a window in one process sends a message to a window in another. (One reason is that the operating system combines the message queues of the multiple processes in this case.) This arrangement should be avoided when feasible. This does not apply to CG/JS mode in the Windows operating system.

While an application could maintain its own record of which process created each window, calling creation-process may be more convenient. See About using multiple windowing threads in a Common Graphics application in cgide.html.


cross-section-box

Function, cg package

Arguments: grid-widget row-or-row-section column-or-column-section &optional include-border-p box

Returns a box for the intersection of a grid-row or grid-row-section with a grid-column or grid-column-section. The box excludes any parts of the sections or subsections that are currently scrolled out of view.

When the specified cross-section is scrolled completely out of view, this function returns nil.

grid-widget is the grid-widget itself.

row-or-row-section is either a grid-row or a grid-row-section.

column-or-column-section is either a grid-column or a grid-column-section.

If include-border-p is true, then the area occupied by the border lines at the right and bottom edges of the cross-section is included in the returned box. Otherwise it is excluded.

box may be either a box (see make-box) or nil. If a box, then that box is modified and returned. If nil, a new box object is created and returned. Passing a scratch box avoids consing one that must be garbage collected.

See also section-box and invalidate-section.


current-hotspot

Generic Function, cg package

Arguments: hotspot-mixin

Returns the hotspot that is currently under the mouse in the hotspot-mixin window, or nil if none.


current-instance

Generic Function, cg package

Arguments: object-editor

Returns the particular instance that an object-editor is currently displaying, if any, or else returns nil. An application should not modify this property. To display an arbitrary instance call display-instance instead.


current-line-number

Generic Function, cg package

Arguments: stream

Returns an integer indicating the current line where selected text starts or, if there is no selected text, where the text cursor is located. 0 indicates the first line. stream can be a multi-line-editable-text control. It can also be a text-edit-window or text-edit-pane.

See also current-text-column.


current-position

Function, cg package

Arguments: graphical-stream

Returns the current position of the specified graphical-stream, from which lines and text may be drawn. Unlike ncurrent-position, this function always creates the position object to return. See ncurrent-position for more information.


current-position-x

Function, cg package

Arguments: graphical-stream

Returns the X coordinate of the current position of the specified graphical-stream, from which lines and text may be drawn. See ncurrent-position for more information.


current-position-y

Function, cg package

Arguments: graphical-stream

Returns the Y coordinate of the current position of the specified graphical-stream, from which lines and text may be drawn. See ncurrent-position for more information.


current-text-column

Generic Function, cg package

Arguments: stream

Returns an integer indicating the current text column where the selected text of stream begins or, if there is no selected text, where the text cursor is located. Zero indicates the leftmost text column.

stream can be a multi-line-editable-text control, a text-edit-window, or a text-edit-pane.

See also current-line-number.


cursor

Generic Function, cg package

Arguments: window-or-dialog-item-or-hotspot

Returns the current mouse cursor of window-or-dialog-item-or-hotspot, which determines the appearance of the mouse cursor whenever it is inside that window (see basic-pane), widget (see dialog-item), or hotspot.

Calling (setf cursor) will set the current mouse cursor. An alternative is to call (setf cursor-name).

The value may be either an instance of the cursor class or a "cursor handle" that is the value of one of the built-in mouse cursor variables such as cross-cursor.

A cursor handle in CG/JS mode is a string that JavaScript uses as the name of the cursor, while in Windows desktop mode it is an integer. In CG/JS you could specify a JavaScript mouse cursor name that is not one CG's standard choices, such as "grab" for a hand that is grabbing rather than pointing, from Mozilla's list.

The value may also be nil, which for a window means to remove the mouse cursor completely when it is inside the window, and for a widget means to use the default cursor for that widget, which is usually the arrow cursor. For a hotspot, nil means to use the parent window's cursor.

The value may also be the keyword :default, which means to use the default cursor for either a window or a widget. The default value is :default for a window and nil for a widget or hotspot. The default cursor image is typically an arrow cursor (see arrow-cursor).

The mouse cursor of a window is used only in the interior of the window, and it is not possible to set the cursor for the frame area of a window. Similarly, certain areas of some controls, such as the column headers of a list-view control or the body of a tab-control, are not customizable and will not show the custom cursor that is assigned to the control.

To use different mouse cursors in different areas of a single window's interior, you can write a mouse-moved method that specializes on the window's class and which calls (setf cursor) on the window, passing a different cursor depending on the cursor-position argument that was passed to mouse-moved. Alternately, you could write a cursor method that returns a different cursor based on the value returned by a call to ncursor-position or cursor-position.

See the section on mouse cursors in cg-pixmaps.html for more infomation.


cursor-handle

Generic Function, cg package

Arguments: cursor

Returns the cursor handle of cursor if it has one, or else nil. cursor should be a cursor instance.

There is probably no need to call this function, because either a cursor handle or a cursor object can be passed to (setf cursor).


cursor-name

Generic Function, cg package

Arguments: object

Returns the name of the mouse cursor of object if it has one, or else nil. object may be a window, a widget (dialog-item), or a hotspot.

The setf of this function can be called to set the cursor of an object from its keyword name, rather than from the cursor instance or its cursor-handle. See the section on mouse cursors in cg-pixmaps.html.


cursor-position

Function, cg package

Arguments: window-or-screen

Returns the current mouse cursor position within window-or-screen. The screen is the value returned by (screen *system*). See screen and *system*.

CG/JS Note: In CG/JS mode, this will return a zero-zero position if the mouse has not yet been moved after the application has started up, because CG can know the position only from mouse movement messages.

The setf of this function may be called to move the mouse cursor programmatically. This may be useful, for example, for moving the mouse cursor to the center of an object that the user is about to drag. On the other hand, such programmatic moves can be annoying to a user with a physical (rather than a touch) mouse because such a user might have to lift the physical mouse in order to once again make the the physical mouse's range of movement match the mouse cursor's range on the screen. (If the physical mouse is near the edge of the desk and the cursor jumps to the top of the screen programmatically, the user cannot bring it back to the bottom without lifting the mouse and repositioning it on the desk.)

See also ncursor-position.


cursor-size

Generic Function, cg package

Arguments: stream

Returns two values, which are the width and height (in pixels) of mouse cursors on the platform being used. When creating a custom mouse cursor from a texture (see the section on Mouse Cursors in cg-pixmaps.html), the texture should be this size.

See also fill-texture.


custom-status-bar-font

Generic Function, cg package

Arguments: configuration

Allows overriding the system default status-bar font. The value should be either a font object or nil to use the system default font. This applies to standalone applications as well as the IDE.


custom-tooltip-font

Generic Function, cg package

Arguments: configuration

Allows overriding the system default tooltip font. The value should be either a font object or nil to use the system default font. This applies to standalone applications as well as the IDE.


cut-command

Generic Function, cg package

Arguments: window-or-widget

Deletes an object from the specified window or widget and places it onto the clipboard.

This function behaves just as copy-command does, except that it calls cut-selection rather than copy-selection so that the copied object is also removed from the window if possible. See copy-command for more information.

See cg-clipboard.html.


cut-selection

Generic Function, cg package

Arguments: window-or-widget

Returns an object from the specified window or widget that is suitable for placing onto the clipboard, or nil if no suitable object is found. Also deletes the returned object from the window or widget when it knows how to do so. This function is called by cut-command, which does the actual placing of the object onto the clipboard. An application could call either function, or add methods to either in order to extend the clipboard functionality.

window-or-widget should be an instance of a basic-pane subclass or a dialog-item subclass.

If a cut was done, then a second value is also returned to indicate the suitable clipboard format, as described under copy-selection.

The default method just calls copy-selection, and so does not delete the copied object. The methods for editable-text-pane and text-edit-pane return and delete the selected text, if any. The method for rich-edit-pane returns a rich text string for the selected text if any, and deletes the text. The method for combo-box returns and deletes the selected text if its typable property is true, and otherwise does nothing and returns nil.

The methods for single-item-list-pane and multi-item-list-pane will return the selected item or items and also delete them from the range of the associated dialog-item. The method for dialog-item simply calls cut-selection on the window of the dialog-item if the widget is currently on a parent window. See copy-selection for a note abouting adding additional methods for other types of widgets.

An around method on widget-window causes nothing to be done if window-or-widget is either a dialog-item or its associated window, and the widget's cuttable property is nil. By default, CUTTABLE is true only for text-editing widgets.

An anomaly: When called on a rich-edit-pane in Windows, it is cut-selection rather than cut-command that actually places the object onto the clipboard. This is due to a problem with mapping the Common Graphics behavior onto the Windows clipboard and rich-edit APIs. In this case, both the rich text string and the plain text string are placed onto the clipboard, with the rich text string being topmost on the lisp clipboard stack.

Compatibility notes

In releases prior to 7.0, this function passed its action to the lowest selected descendent child window of the specified window, though some applications may not desire such automatic redirection. The functions focus-component, get-focus, or selected-window may be useful for finding a suitable widget or window to pass to this function. Earlier releases also returned the window where the copy was actually done as the first value, and the copied object as the second value.

See cg-clipboard.html.


cuttable

Generic Function, cg package

Arguments: *dialog-item *

Returns whether anything will be done when cut-selection or delete-selection is called on dialog-item or its widget-window. The value of this property may be set by calling (setf cuttable), or it may be set in the inspector when laying out forms in the IDE.

If nil, then cut-selection or delete-selection will do nothing and will return nil. Otherwise they will proceed as usual (though deletion is still done only when there is an applicable method to do it).

The default value is t for text-editing widgets, where text deletion is typically allowed, and nil most everywhere else. The default is t for a combo-box, though this applies only when its typable property is true and affects only the typable pane. The value may be set to true for a single-item-list or multi-item-list to cause cut-selection and delete-selection to remove the selected item(s) from its range.

See also pastable and cg-clipboard.html.


data-object

Generic Function, cg package

Arguments: grid-row

Returns the arbitrary object from the application that is being represented by this grid-row. Typically, a data-object is assigned to a grid-row by passing the :data-object initarg to make-instance when creating the grid-row. draw-cell methods then often call data-object to retrieve values from the object to display in various cells.

For example, in the employee grid example the data-object of each grid-row is an instance of the "employee" class. These employee instances are completely independent of any user interface for them, and contain the real-world data for each employee. Whenever the grid wants to display some attribute of an employee in a grid-cell, it calls the grid-column's data-reader function on the grid-row's data-object to retrieve the needed real-world information from the employee object. The employee grid example can be found on the Examples tab of the Navigator dialog.

data-object is a property of the grid-row and column-header-row classes.

See the grid-widget class for an overview of writing grid-widget code.


data-read-converter

Generic Function, cg package

Arguments: grid-column

Returns the function that converts the programmatic value returned by this grid-column's data-reader function into the actual value that is displayed in a grid cell. This is similar to the on-print property of many controls. Typically the function returns a formatted string, but may return other sorts of values for grid-columns that represent data with non-strings (such as the bar-chart in the employee grid example). The employee grid example can be found on the Examples tab of the Navigator dialog.

The function should take a single argument, which is an arbitrary data-object attribute value.

For example, in the employee grid example, the Department column's data-reader is employee-department, which is simply the reader method for the department slot of an employee instance. When called on an employee instance, this function returns a symbol like :marketing. This symbol is fine for representing the department programmatically, but to display it nicely in a grid cell, the Department grid-column has the data-read-converter "capitalize-if-symbol", which is a function that takes the symbol :marketing and returns the string "Marketing" to display in the grid cell.

A special case is that the values that appear in the drop-down list of a combo-box-column-mixin cell are formatted by the on-print function of the grid-column even though the value appearing in the grid cell itself is formatted by the column's data-read-converter function as with other grid cells. To use the same formatting in both places, specify the same function for each of these properties.

NOTE: Your application does not call the data-read-converter function; it supplies the data-read-converter function which is then called automatically by the system as needed.

See the spreadsheet-value-printer function for an example of how a data-read-converter function converts data that the grid-widget reads from somewhere into the strings that it displays in grid cells.

data-read-converter is a property of the grid-column and row-header-column classes.


data-reader

Generic Function, cg package

Arguments: grid-column

Returns (or sets with setf) a function that retrieves the value to be displayed in a grid cell. This function is called by the default read-cell-value method, and supplying a data-reader function and a data-object function is an alternative to writing your own read-cell-value method. The data-reader may be nil if this facility is not used. The default value is nil.

The data-reader function is a property of a grid-column, and is called once for each grid-row that intersects that column to find the value to be displayed in the cell at that intersection. The function should take a single argument, which is the grid-row's data-object. The function is typically simply the reader function of the data-object for the attribute represented by this grid-column. If this column is accessing a slot that has no writer function or the writer function is not known, then the data-slot property could be used instead.

For example, in the employee grid example, each row represents an employee, and the Department column represents the department attribute of each employee. The data-reader function of the Department column is employee-department, which is simply the reader method for the department slot of an employee instance. To find the value to represent in the Department column for each employee, the Department column's data-reader function (employee-department) is called on the data-object (an employee) of each grid-row. The employee grid example can be found on the Examples tab of the Navigator dialog.

NOTE: Your application typically will not call the data-reader function, and instead will supply the data-reader function which is then called automatically by the system as needed. Specifically, the built-in column classes such as editable-text-column-mixin will call the data-reader whenever they draw a cell, and a custom draw-cell method that an application supplies may call the default read-cell-value method, which calls the data-reader. Otherwise the draw-cell method may use some custom technique to find the value to draw, and a data-reader method is not needed at all.

data-reader is a property of the grid-column and row-header-column classes.

See the grid-widget class for an overview of writing grid-widget code.


data-slot

Generic Function, cg package

Arguments: grid-column

Returns the name of a slot that holds values to be displayed in cells of a grid-column, or else nil if this property is not being used. The value may be set at creation time by passing the data-slot initarg, or any time later by calling (setf data-slot). The default value is nil.

This property will be used when reading cell values only if the default read-cell-value method is not overridden and the grid-column has no data-reader function. It will be used when writing cell values only if the default write-cell-value method is not overriden and the grid-column has no data-writer function.

If this property is used, then when a grid cell is drawn, the value to display is found by calling slot-value with the data-object of the grid-row along with this slot name. If the user interactively edits the value in a grid cell, the new value is written back into application data by calling (setf slot-value) with the data-object of the grid-row along with this slot name and the new value.

It is usually preferable to use data-reader and data-writer functions because they will trigger the usual side effects of a slot's reader and writer functions. But data-slot can be useful for slots that do not have reader and writer functions, or when these functions are not known.

A special feature of a data-slot value is that it may indirectly access a slot of an object that's stored in a slot of the grid-row's data-object. This is done by using a value that is a list of slot names rather than a single slot name. The first slot name in the list should be a slot of the grid-row's data-object, the second slot name in the list should be a slot of the object that is found in the first slot, and so on. For example, if the data-object of each grid row is a patient object, and this grid column is editing the hospital of each patient, then the column's data-slot might be the list (hospital ceo phone-number) to access the phone number slot of the object that's in the CEO slot of the object that's in the hospital slot of the patient of each grid row. A class-grid makes use of this feature internally, but an application could use it directly as well.


data-write-converter

Generic Function, cg package

Arguments: grid-column

Returns the function that takes a value that has been entered interactively in a grid cell, and converts it into a value to be used programmatically by the application. The value returned by this function will be written to the grid-row's data-object by the grid-column's data-writer function.

The function should take a single argument, which is a value that the user has interactively entered into a cell of the grid-column that is using this function to convert user input.

A data-write-converter is typically used when the user can type a string into a grid cell, and the string needs to be converted to some other type of value for internal use. For example, in the employee grid example, the Department column's data-write-converter is make-department-symbol, which takes a department string like "Sleeping" that the user has typed into the grid cell, and converts into a keyword symbol like :sleeping, which is the internal representation of a department.

data-write-converter is a property of the grid-column and row-header-column classes.


data-writer

Generic Function, cg package

Arguments: grid-column

Returns (or sets with setf) a function that takes a value that has been entered interactively into a grid cell and writes the value into the application object that is being represented in the grid cell. This function is called by the default write-cell-value method, and supplying a data-writer function and a data-object function is an alernative to writing your own write-cell-value method. The data-writer may be nil if this facility is not used. The default value is nil.

The data-writer function is a property of a grid-column, and is called whenever the user enters a value into a cell of that column. The function should take two arguments, which are (1) the value that has been entered by the user and optionally converted by the grid-column's data-write-converter function, and (2) the grid-row's data-object. The function is typically simply the writer function of the data-object for the attribute represented by this grid-column.

For example, in the employee grid example, each row represents an employee, and the Department column represents the department attribute of each employee. The data-writer function of the Department column is (setf department), which is simply the writer method for the department slot of an employee instance. If the user enters "Sleeping" in a cell of the Department column, then the Department column's data-writer function, (setf employee-department), is called on the data-object (an employee) of the grid-row that the modified cell is in. The employee grid example can be found on the Examples tab of the Navigator dialog.

NOTE: Your application does not call the data-writer function; it supplies the data-writer function which is then called automatically by the system as needed.

data-writer is a property of the grid-column and row-header-column classes.

See the grid-widget class for an overview of writing grid-widget code.


db-grid-add-button-on-change

Function, cg package

Arguments: widget new-value old-value

This is the on-change function of an Add button that may be automatically created for a slot-editing-class-grid.

This symbol is exported only because it can appear in code that is generated for object-editor forms. It should not be used by application code.


db-grid-create-button-on-change

Function, cg package

Arguments: widget new-value old-value

This is the on-change function of a Create button that may be automatically created for a slot-editing-class-grid.

This symbol is exported only because it can appear in code that is generated for object-editor forms. It should not be used by application code.


db-grid-delete-button-on-change

Function, cg package

Arguments: widget new-value old-value

This is the on-change function of a Delete button that may be automatically created for a slot-editing-class-grid.

This symbol is exported only because it can appear in code that is generated for object-editor forms. It should not be used by application code.


db-grid-remove-button-on-change

Function, cg package

Arguments: widget new-value old-value

This is the on-change function of a Remove button that may be automatically created for a slot-editing-class-grid.

This symbol is exported only because it can appear in code that is generated for object-editor forms. It should not be used by application code.


decrement-pixmap-name

Generic Function, cg package

Arguments: calendar-widget

The name of the upper-left pixmap for displaying the previous page in a calendar widget. It should have the same size as the increment pixmap.

See also increment-pixmap-name, the calendar class and the function ask-user-for-date.


def-cg-ocx-control

Macro, cg package

Arguments: ocx-object-name-string &key doc-path use-native-size toolbar-string-or-icon toolbar-after toolbar-tooltip toolbar-help-string

This macro is supported on Windows only.

Defines a Common Graphics dialog-item class, and an associated widget-window class, for one of the OLE controls that was defined by a call to ole:def-ole-linkage. All such widgets will be subclasses of the ocx-widget class, and their widget-windows will be subclasses of the ocx-widget-window class. Methods for the Common Graphics classes that are created will be defined in the package that was defined by the ole:def-ole-linkage form.

A call to def-cg-ocx-control should be a top-level form in an application source code file, and should be placed somewhere after a call to ole:def-ole-linkage that loads the OLE application that defines the control. If the two forms are in the same file, you should place the ole:def-ole-linkage form inside an (eval-when (compile load eval) ...) form to ensure that that macro call is evaluated to create its new package before the def-cg-ocx-control form is macroexpanded (see the example at the bottom of this page). Compiling an OLE control can take a fair amount of time, so in an IDE project (for example) it is a good idea to place these forms in a project file by themselves, so that the control does not need to be recompiled whenever you modify other code in the same file.

Arguments

Note about property names

def-cg-ocx-control will define Common Graphics properties for any OLE get and put functions that take a single argument (which is the widget itself). In the IDE inspector, you will see these properties mixed with the usual properties that are defined by Common Graphics. In a case-sensitive lisp, the standard Common Graphics properties will be entirely lowercase, while the properties provided by the OCX control will be mixed case. Sometimes there will be two properties with the same name that differ only in string case. These symbols do not conflict, even in a case-insensitive lisp, because the package that is created for the symbols that are provided by the OCX control never uses any other package and is never used by any other package. This is necessary because we cannot predict what symbol names an OCX control may use.

Note that you don't need to define the WebBrowser control, because Common Graphics defines it internally. It is exported as the cg.ie:cg-WebBrowser dialog-item class, though for this particular control it may be preferable to use the platform-independent subclass called html-widget.

Here is how Common Graphics defines the WebBrowser control. You should not evaluate this code because Common Graphics has already done so, but you could define some other OCX control similarly.

;;  Code sample for information only. It should not be
;;  evaluated by users.
;;
(eval-when (compile load eval)
  (ole:def-ole-linkage #:cg.ie :application "InternetExplorer"))

(def-cg-ocx-control "WebBrowser"
    :doc-path (merge-pathnames "WebBrowser.txt"
                               *compile-file-pathname*))

See also ole.html.


default-process-for-events

Function, cg package

Arguments:

This function is used only in CG/JS mode. It returns nil by default, but the setf of this function can be called to specify a particular process that should receive events that are not associated with a window. The large majority of events are associated with a window, and those events get dispatched to the creation-process of the window. Other events will get passed to the initial CG process unless the setf of this function is called to specify some other process. Timer events in particular are not associated with any window, and there may be others.

(setf (default-process-for-events) my-process-for-windowless-events)

defvar-cg

Macro, cg package

Arguments: var &optional init (doc nil docp) even-on-virtual-threads

This macro works just like defvar, except that every CG process that's created will automatically get its own binding for the symbol. (This macro also has an additional even-on-virtual-threads parameter, but it is no longer used and is kept only for backward compatibility.)

This may be useful when enhancing an application so that it works with multiple simultaneous web browser clients. (That is allowed when the Max Clients option on the CG/JS tab of the Project Manager is greater than one.) That would not work if client-specific information is stored in global variables, so converting defvar forms to defvar-cg is a simple way to handle that particular problem.


default-256-color-palette-vector

Function, cg package

Arguments:

Returns a 256-member vector of rgb objects with the colors spread out evenly. This may be useful when Windows is running in 256-color (8-bits-per-pixel) mode in order to map a higher-resolution pixmap of unknown colors into 256 colors.

To do so, call open-palette on a window and the color vector returned by this function to create a palette for that window, then apply setf to palette to assign the palette to the window, and then call copy-to-stream to copy the high-resolution pixmap to the window. The image in the window should approximate the high-resolution pixmap about as well as can be expected with 256 colors without having additional knowledge of the particular colors used in the pixmap.


default-application-window-subkey

Function, cg package

Arguments:

Returns the default value for the subkey argument of the functions add-application-window, find-application-window, and remove-application-window. It is probably not useful for an application to call this function.

Now that GTK is no longer supported, the returned value is always the current process.

The idea behind the subkey argument to add-application-window was to allow windows in distinct processes to have the same name, and still allow find-application-window to find the correct window when called in event-handler callback code of windows in the same process. This works because event callback code runs in the creation-process of each window.


default-background-color

Generic Function, cg package

Arguments: object

Returns the default background color for object. This color will be used as the background color when the value of the background-color property is nil.

The value must be an RGB color (as returned by make-rgb). Note that the value cannot be an HLS color (as returned by make-hls). If you use HLS colors, apply hls-to-rgb to them before setting this property, and apply rgb-to-hls to get the HLS equivalent of a RGB value.

The built-in methods are specialized on the window class. Thus, for example, the default for dialog-mixin is returned by system-dialog-background-color and for basic-pane is returned by system-background-color.

Contrast with the built-in method for default-foreground-color, which is the value returned by system-foreground-color whatever the type of window.


default-button

Generic Function, cg package

Arguments: dialog

Returns the default-button object on dialog if dialog has a default button and returns nil if dialog does not have a default button. If dialog has more than one default-button (strongly discouraged but not impossible), one is returned but which one is not determined. See the default-button control.


default-cell-3d-border

Generic Function, cg package

Arguments: grid-widget-or-section

Returns whether a pseudo-three-dimensional border will be drawn around each cell in the specified grid-widget, grid-row-section, or grid-column-section. If this property is true for any of these objects that contain a given cell, then that cell will have a 3d border. The setf of this function may be called to change the 3d border, at which time the grid will be drawn as needed to display the new borders.

The above actually describes the behavior of the default cell-3d-border method. An application may supply cell-3d-border methods to override this behavior for some or all of the cells.

If the value is nil (the default), then no 3d borders will be drawn. If it is the keyword :sunken-edge, then 3d borders will be drawn that appear sunken (making the grid cells appear raised). If it is t, then 3d borders will be drawn that appear raised (making the grid cells appear sunken).

If the regular (non-3d) borders of the cells are non-zero (see border-width and default-cell-border-width) while 3d borders are turned on, then both the regular and 3d borders are drawn, with the 3d borders just inside the regular borders. 3d borders may look best without the regular borders, so it is likely desirable to set the width of the regular borders to zero when using 3d borders.


default-cell-border-color

Generic Function, cg package

Arguments: grid-widget-or-section

Returns the color, if one has been specified, that will be used by default to draw the row and column borders within the specified grid-section or within all of the grid-row-sections and grid-column-sections of the specified grid-widget. The setf of this function may be called to change the color, at which time the grid will be drawn as needed to display the new color. This default may be overridden by specifying the border-color property of individual grid-row and grid-column instances.

The value may be either an RGB color object (as returned by make-rgb or ask-user-for-color), or a symbol whose global value is an RGB object, or nil. The initial value is nil. When nil, effective-border-color will find a color to use in some other way.


default-cell-border-width

Generic Function, cg package

Arguments: grid-widget-or-section

Returns the width, if one has been specified, that will be used by default to draw the row and column borders within the specified grid-section or within all of the grid-row-sections and grid-column-sections of the specified grid-widget. The setf of this function may be called to change the width, at which time the grid will be drawn as needed to display the new border width. This default may be overridden by specifying the border-width property of individual grid-row and grid-column instances.

The value may be either a non-negative-integer or nil. The initial value is nil. When nil, effective-border-width will find a width to use in some other way. Zero means to draw no border at all (though default-cell-3d-border may still be used to draw a separate 3d border).


default-clipboard-format

Generic Function, cg package

Arguments: window

Returns the clipboard format that will be used by default when copying, cutting, and pasting in window. The built-in methods return :text for a text-edit-pane, :rich-text for a rich-edit-pane, and :pixmap for bitmap-pane or drawable-pane. An application could conceivably add a custom default-clipboard-format method for one of its own text-edit-pane subclasses.

See cg-rich-text.html for information about rich text editing in Common Graphics. See also cg-clipboard.html.


default-closed-pixmap

Function, cg package

Arguments:

Returns the default pixmap to use for all of the items of an outline that have subitems when those subitems are currently hidden. The image is a closed file folder.


default-column-width

Generic Function, cg package

Arguments: class-grid

Returns the section-size that will be used for any new grid-columns in the body of a class-grid when no explicit size is specified for those columns. The value may be set with the default-column-width initarg or by calling (setf default-column-width).

Changing the value affects only grid columns that are created later by modifying the edited-slots property of the class-grid.


default-error-handler-for-delivery

Generic Function, cg package

Arguments: project-or-app

This project property can be used to handle all unexpected errors that might be signaled in a delivered application that was generated from a project. The value of this property can be set on the Advanced tab of the Project Manager dialog, using the widget labeled Default Error Handler for Delivery.

The setf of this function may be called to set the value programmatically, though typically you would set the value interactively in the Default Error Handler for Delivery widget on the Advanced tab of the Project Manager dialog.

The value of this property should be the name of a function that accepts one argument, which will be the condition object for an error that was signaled. The default value is report-unexpected-error-and-exit, which displays a simple dialog about an unexpected error and then exits the application. An alternate built-in function is write-backtrace-to-file, for debugging a generated application that is crashing or failing to start up.

The function will be called whenever an otherwise unhandled error is signaled in the event-handling loop of an application that was generated from a project, if and only if the Enable Debugging of Runtime Errors option has been disabled on the Build tab of the Project Manager dialog (see ide:build-flags. The global variable *show-console-on-standalone-error* must also be true, as it is by default. If the function returns, event-loop will continue handling events.

To handle errors in a meaningful way, an application would typically use handler-case or handler-bind forms around small pieces of code in order to handle the particular errors that might be signaled in those places. But it may also be desirable to further trap all other unexpected errors, to allow the user to attempt to recover before exiting. Using this project property for that purpose is an alternative to wrapping general event handlers around all individual event-handling functions in a Common Graphics application, which could be very tedious.

As an example, a default error handler could call pop-up-message-dialog to report that an unexpected error has occurred, and give the user an option to let the program attempt to save their work before exiting. It could then do a save (perhaps after first doing a backup), and then call excl:exit to exit the application. The function alternately could return rather than calling excl:exit, to allow the user to continue working, though that's not recommended in this general case where the application is in an unpredictable state due to an unknown error. It could also exit the program by calling its own usual exit function (or call user-close on the main window, for example) rather than calling excl:exit, if the usual side effects are not too risky while in an unknown state.

In a generated application, this property will be on the app object rather than on a project, since the project system does not exist in a generated application. An application could change this app property at runtime if desired; it exists on the app object in the IDE as well, though it is not used there.

If an error is signaled in an application's default-error-handler-for-delivery function itself, then Lisp will simply exit, and it may not be obvious why. In particular, that can happen if the error-handling code uses functionality from a Lisp module that exists in the IDE but not at runtime. To debug that, it may be necessary to artificially call the code that's in the error-handling function in a test version of the standalone app where Enable Debugging of Runtime Errors is turned on (see the Build tab of the Project Manager dialog).


default-foreground-color

Generic Function, cg package

Arguments: window

Returns the default foreground color for window. This color will be used as the foreground color (for drawing and for text) when the value of the foreground-color property of window is nil.

The value must be an RGB color (as returned by make-rgb). Note that the value cannot be an HLS color (as returned by make-hls). If you use HLS colors, apply hls-to-rgb to them before setting this property, and apply rgb-to-hls to get the HLS equivalent of a RGB value.

With the built-in methods, this is always the value returned by system-foreground-color, usually black unless the end user has set up a different text color in the Windows Control Panel.

Contrast with default-background-color, which has different defaults for various window classes, such as system-dialog-background-color for dialog-mixin and system-background-color for basic-pane.


default-gray-palette-vector

Generic Function, cg package

Arguments: system

This function has been replaced with default-gray-pixmap-color-vector and the new function should be used in place of this one. The new function does not take any arguments. This function takes one argument, but the one argument is in fact ignored. This function is kept for backward compatibility only. See default-gray-pixmap-color-vector for information on what this deprecated function does.


default-gray-pixmap-color-vector

Generic Function, cg package

Arguments:

Returns the default-gray-pixmap-color-vector. This can be used to make an image that normally uses default-pixmap-color-vector appear "unavailable" by swapping this color vector into the texture-info that is used for the image and redrawing the image as usual with copy-to-stream or copy-pixels-to-stream.

default-gray-pixmap-color-vector is a property of the system class.

In releases prior to 7.0, this function was named default-gray-palette-vector and took one argument, which was in fact ignored. New code should use this function called without arguments.


default-grid-sorter

Generic Function, cg package

Arguments: value-one value-two

This function is called by sort-grid if the on-sort-predicate function of the sort-column of the grid-widget is not a function name or function object.

As the examples below show, returns true is value-one is smaller (numerically or as strings) than value-two.

Whenever both of the values are numbers, it sorts the values numerically. Otherwise it sorts all values alphanumerically, where a string is compared directly and a symbol uses its symbol-name, but other values will cons a string on each call with prin1-to-string. So sorting may cause substantial consing unless either every value is a number or every value is either a string or a symbol.

Examples:

cg-user(44): (default-grid-sorter 1 2)
t
cg-user(45): (default-grid-sorter 2 1)
nil
cg-user(46): (default-grid-sorter "hello" "goodbye")
nil

default-header-justification

Generic Function, cg package

Arguments: header-control

Returns the default header justification as passed by the :header-justification initarg to (make-instance 'header-control). The values can be :left, :right, or :center.

default-header-justification is a property of the header-control class.


default-header-width

Generic Function, cg package

Arguments: header-control

Returns the default header width as passed by the :header-width to (make-instance 'header-control).

default-header-width is a property of the header-control class.


default-height

Generic Function, cg package

Arguments: window-or-configuration

Returns the height to be used for a newly created window if an explicit height was not specified in the call to make-window. This function is called automatically by the system and should not be called by applications, but an application may supply default-height methods to specify the default sizes for its window subclasses.

default-height is called after the Lisp object for the window has been created but before the actual window has been created by the operating system. It returns an integer denoting the height to use for the new window.

The default version of these methods (for simple-streams) work as follows. The height is determined by:

  1. If a method is supplied for the class of the window argument, and that method returns an integer (rather than nil), that value is used for the height. Otherwise:

  2. If the value of (default-height (configuration \*system\*)) is true, use that value for the height. (It is nil initially though.)

  3. If (default-height (configuration \*system*\)) is nil, multiply the height of the screen, (height (screen \*system\*)), by (default-height-factor (configuration *system*)) and use the result as the height.

default-height methods may be added for window subclasses of an application in lieu of passing the equivalent initargs for each window instance.

You can pass the :exterior-top-left argument to make-window in order to specify a particular position for the top-left corner of a window without overriding these default size methods. The top-left position will otherwise default to being offset somewhat from the position at which the previous window was created.

default-height is a property of the configuration class. See also default-width and default-top-left.


default-height-factor

Generic Function, cg package

Arguments: configuration

Returns the default ratio of new window height to screen interior. This value is used to calculate the height of a new window when the arguments to make-window do not determine the height.

default-height-factor is a property of the configuration class.


default-init-function

Function, cg package

Arguments:

default-init-function is the default ide:on-initialization function for a project. It creates and displays the running window for the main form of the project, and then returns that window so that the application will exit when the main window is closed.

Below is the complete code for this function, which an application may model after if it needs to use a custom ide:on-initialization function.

(defun default-init-function ()
  (let* ((maker (main-window-maker (app *system*)))
         window)
    
    ;; This default project on-initialization function expects
    ;; the project to have a main form to run.  For a project
    ;; that uses no windows at all, you would need to substitute 
    ;; a different on-initialization function.
    (unless maker
      (error "The project has no main form to run.  Either add a form ~
                 to the project or give the project a different ~
                 on-initialization function."))
    
    ;; Call the main form module's maker-function to create its window.
    (setq window (funcall maker
                          
                          ;; When in a Run Project in the IDE,
                          ;; run the main form on the screen (rather
                          ;; than on the IDE owner window where
                          ;; individual forms are run) to more completely
                          ;; emulate the standalone application.
                          ;; (The preferred initarg is now :owner, but
                          ;; :parent also works with maker-functions
                          ;; that were generated in pre-6.0 versions.)
                          :parent (screen *system*)))
    
    ;; Cache the main window so that its finder function will
    ;; find it later.
    (when window
      (add-application-window window)
      
      ;; Select the window if needed so that the end user sees it.
      ;; A custom on-initialization function might want to customize
      ;; the window contents in some way before revealing it here.
      (select-window window)
      
      ;; This call may be needed especially in Windows 2000 to
      ;; ensure that the app comes to the front.
      (set-foreground-window window))
    
    ;; Return the main window of the application, to tell
    ;; do-default-restart to call event-loop for us, passing the
    ;; window so that event-loop exits when the window has been closed.
    ;; Alternately, we could call event-loop ourselves with a
    ;; custom exit-test, and return anything but a window when
    ;; it returns.
    window))

default-inverted-texture-info

Generic Function, cg package

Arguments: system

This function is deprecated in favor of the global variable *default-inverted-texture-info*. This function may cease to be supported in a future release. In the current release, it simply returns the value of *default-inverted-texture-info*. The system should be the current system, which is the value of *system*.


default-leaf-pixmap

Function, cg package

Arguments:

Returns the default pixmap to use for all of the items of an outline that do not have subitems. The image is a blank page.


default-menu-on-click

Generic Function, cg package

Arguments: menu menu-item window-or-screen

The symbol default-menu-on-click is the default value of the on-click event-handling property of a menu.

The default default-menu-on-click method simply returns the value of the chosen menu-item. Therefore, when pop-up-menu is called on a menu that uses this default on-click handler, the value of the chosen menu item is simply returned from pop-up-menu, and the calling function must decide what to do with the value. (Alternate on-click handlers, such as the built-in function funcall-menu-item, can be used instead to process any chosen item in some standard way before pop-up-menu returns. In fact, this must be done for pull-down menus, since they do not return values to the application.)

When the menu is a shortcut-menu, the default on-click function is still default-menu-on-click, but a different method of this generic function is used. This method expects the menu-item's value to be one of the following things:

menu is the menu that contains the chosen menu-item.

menu-item is the menu-item that was chosen.

window-or-screen is either the window on which the menu was invoked with pop-up-menu, or else the window on which the menu was defined.


default-opened-pixmap

Function, cg package

Arguments:

Returns the default pixmap to use for all of the items of an outline whose subitems are currently being shown. The image is an open file folder.


default-page-height

Generic Function, cg package

Arguments: window interior-height scrollbarp

Returns a default page-height to use for window when no page-height has been explicitly specified with either a setf of the page-height function or the :page-height initarg. interior-height is the interior height of the window. scrollbarp is true if the vertical scrollbar was enabled for the window when it was created. The returned value is always in stream units (see cg-coordinates.html).

The default method returns the interior-height if the scrollbar is not enabled, and otherwise returns the height of the screen. An application may add default-page-height methods to define default page-heights for its own window classes. The method should always return a height and never return nil.

See also page-height and explicit-page-height (and also page-width, default-page-width, and explicit-page-width.)


default-page-width

Generic Function, cg package

Arguments: window interior-width scrollbarp

Returns a default page-width to use for window when no page-width has been explicitly specified with either a setf of the page-width function or the :page-width initarg. interior-width is the interior width of the window. scrollbarp is true if the horizontal scrollbar was enabled for the window when it was created. The returned value is always in stream units (see cg-coordinates.html).

The default method returns the interior-width if the scrollbar is not enabled, and otherwise returns the width of the screen. An application may add default-page-width methods to define default page-widths for its own window classes. The method should always return a width and never return nil.

See also page-width and explicit-page-width (and also page-height, default-page-height, and explicit-page-height.)


default-palette-vector

Generic Function, cg package

Arguments: system

This function has been replaced with default-pixmap-color-vector and the new function should be used in place of this one. The new function does not take any arguments. This function takes one argument, but the one argument is in fact ignored. This function is kept for backward compatibility only. See default-pixmap-color-vector for information on what this deprecated function does.


default-pane-class

Generic Function, cg package

Arguments: frame-with-single-child

Returns the name of the class to instantiate for the single child pane of a frame-with-single-child class (thus, the default method for the bitmap-window class returns the symbol bitmap-pane). If you subclass frame-with-single-child, you should provide a default-pane-class method for your new class.


default-pixmap-color-vector

Generic Function, cg package

Arguments:

Returns the default-pixmap-color-vector. This is a color vector shared by the texture-infos of many Allegro pixmaps for efficiency. It contains the following sixteen colors:

An application pixmap that uses these 16 colors in this order could use this color vector in the colors slot of the texture-info used with the pixmap in order to reduce the total number of color vectors needed by the application. Pixmap-creating programs such as the Paint applet may create pixmaps that use this color order or a similar one that could be edited to this one.

An additional advantage of using default-pixmap-color-vector is that Allegro automatically changes the vector's gray entry to the system-edge-shadow-color, the light-gray entry to the system-dialog-background-color, and the white entry to the system-background-color. This means that button pixmaps using this color vector will automatically appear in the custom colors that the end user has set up in the Windows Control Panel.

default-pixmap-color-vector is a property of the system class.


default-section-border-color

Generic Function, cg package

Arguments: grid-widget

Returns the border color used by sections of grid-widget that do not have a border color specified.

default-section-border-color is a property of the grid-widget class.


default-section-border-width

Generic Function, cg package

Arguments: grid-widget

Returns the border width used by sections of grid-widget that do not have a border width specified.

default-section-border-width is a property of the grid-widget class.


default-tab-height

Generic Function, cg package

Arguments: configuration

Returns the configuration's default pixel-height for tabs on a tab-control. The value nil means defer to the OS default. The current configuration, which provides the default currently in force, is (configuration *system*) (see configuration and *system*).

See the description of the tab-control class/control. default-tab-height is a property of the configuration class.


default-tab-width

Generic Function, cg package

Arguments: configuration

Returns the configuration's default pixel-width for tabs on a tab-control. The value nil means defer to the OS default. The current configuration, which provides the default currently in force, is (configuration *system*) (see configuration and *system*).

See the description of the tab-control class/control. default-tab-width is a property of the configuration class.


default-texture-info

Generic Function, cg package

Arguments: system

This function is deprecated in favor of the global variable *default-texture-info*. This function may cease to be supported in a future release. In the current release, it simply returns the value of *default-texture-info*. The system should be the current system, which is the value of *system*.


default-top-left

Generic Function, cg package

Arguments: window window-width window-height

This generic function is called when a window is created if none of the initargs to make-window (specifically :left and :top, :exterior-top-left, :exterior, or :interior) specifies a position for the window. Returns a default position at which to place the exterior upper-left corner of the new window. An application may add default-top-left methods to specify the default positioning for various window classes.

If the offset-from-selected-window configuration property is turned on (as it is by default), then the default default-top-left method will position the window just down and right (by the height of a titlebar) from the selected child window of the new window's parent window if any. Otherwise it places the window at the most recently used default position, which is initially the upper left of the screen.

A special wrapper method in the IDE defaults any windows that are owned by the invisible IDE owner window (the development-main-window) to a special location selected by the IDE, which is the position where new forms are placed. (When running the IDE, a window will in fact be owned by the IDE owner window if no :parent initarg is passed to make-window; in a standalone application a new window will be an ordinary top-level window by default.)

This generic function is similar to default-width and default-height, but differs in that those are also configuration properties while default-top-left is not a configuration property.


default-width

Generic Function, cg package

Arguments: window-or-configuration

Returns the width to be used for a newly created window if an explicit width was not specified in the call to make-window. This function is called automatically by the system and should not be called by applications, but an application may supply default-width methods to specify the default sizes for its window subclasses.

The default-width is used as described below when a window is created with make-window but neither the :exterior nor :interior arguments are specified.

The default-width is called after the Lisp object for the window has been created but before the actual window has been created by the operating system. It returns an integer denoting the width to use for the new window. The default version of this method (for simple-streams) works as follows. The width is determined by:

  1. If a method is supplied for the class of the window argument, and that method returns an integer (rather than nil), that value is used for the width. Otherwise:

  2. If the value of (default-width (configuration *system*)) is true, use that value for the width. (It is nil initially though.)

  3. If (default-width (configuration *system*)) is nil, multiply the width of the screen, (width (screen *system*)), by (default-width-factor (configuration *system*)) and use the result as the width.

default-width methods may be added for window subclasses of an application in lieu of passing the equivalent initargs for each window instance.

You can pass the :exterior-top-left argument to make-window in order to specify a particular position for the top-left corner of a window without overriding these default size methods. The top-left position will otherwise default to being offset somewhat from the position at which the previous window was created.

default-width is a property of the configuration class. See also default-height and default-top-left.


default-width-factor

Generic Function, cg package

Arguments: configuration

Returns the default ratio of new window width to screen interior. This value is used to calculate the width of a new window when the arguments to make-window do not determine the width.

default-width-factor is a property of the configuration class.


defcomponent

Macro, cg package

Arguments: class-name superclass-names slot-specifiers &rest class-options

Defines a class that has properties, so as to effectively combine a defclass expression with an associated defproperties expression. defcomponent is similar to defclass, except that a :properties option may be specified as follows:

(defcomponent thing
  ((color ...)
   (size ...))
  (:default-initargs
   :color red
   :size 4)
  (:documentation "A silly class")
  (:properties
   (color
    :help-string "Color of the thing."
    :type rgb-or-nil
    :editor-type :color)
   (size
    :help-string "How big the thing is."
    :type positive-integer)
   ))

More examples are on the defproperties page.

The format of the properties option is similar to defproperties except that the symbol define-property is not needed at the beginning of the list for each property.

A property may define any of the following property facets, listed here with the initarg that is used to specify each:

Properties of CLOS classes inherit similarly to slots. Only those facets that differ from the inherited property need be specified for a given class, and properties that have no differing facets need not be specified at all.

Properties are shown on a separate tab of the inspector, and thus can serve as a relatively high-level interface to the object by providing a selected subset of the object's internal attributes, where each property knows to either disallow modification or to cause appropriate side effects upon modification in order to maintain a consistent environment.


define-property

Macro, cg package

Arguments: name &rest args &key reader writer accessor type dependent-properties initarg help-string remake editor-type read-only choices hidden repositioning

Defines an individual property within a defproperties form. On the defproperties page, there is an example which contains examples of calls to define-property.

This macro defines a property but does not associate it with any class or object. A property is an attribute of an object that defines a high-level means of accessing the attribute value. Properties are largely used by the inspector for editing objects that have properties, though they are useful programmatically as well mostly because a property defines how to cause any appropriate side effects when the property value is modified. A property for a CLOS object is typically based on a slot of the object, but properties are generally independent of any internal representation and can be defined for any lisp type.

A property may define any of the following property facets, listed here with the initarg that is used to specify each:

Properties of CLOS classes inherit similarly to slots. Only those facets that differ from the inherited property need be specified for a given class, and properties that have no differing facets need not be specified at all.

Properties are shown on a separate tab of the inspector, and thus can serve as a relatively high-level interface to the object by providing a selected subset of the object's internal attributes, where each property knows to either disallow modification or to cause appropriate side effects upon modification in order to maintain a consistant environment.


defproperties

Macro, cg package

Arguments: class-name &rest properties

Defines a set of properties for a class. A property is an attribute of an object that defines a high-level means of accessing the attribute value. Properties are largely used by the inspector for editing objects that have properties, though they are useful programmatically as well mostly because a property defines how to cause any appropriate side effects when the property value is modified. A property for a CLOS object is typically based on a slot of the object, but properties are generally independent of any internal representation and can be defined for any lisp type. Properties are defined with define-property. The various property initargs are described on that page.

As an example, below is a part of the defproperties expression for the existing control class header-control. Here the properties are defined with define-property. (To make a defproperties form less verbose, each occurrence of the symbol define-property within the form may be excluded if desired, as shown is the second form.)

(defproperties header-control
 (define-property available
   :type boolean
   :editor-type :toggle)
 (define-property header-width
   :type positive-integer
   :reader default-header-width
   :writer (setf default-header-width)
   :editor-type :short-expression)
 (define-property header-justification
   :type justification
   :editor-type :multiple-choice
   :reader default-header-justification
   :writer (setf default-header-justification)
   :choices :justification-values)
 (define-property button-style
   :type boolean
   :editor-type :toggle
   :remake t)
 (define-property on-range-change
   :type event-handler
   :editor-type :function)
 (define-property on-set-focus
   :type event-handler
   :editor-type :function)
 )

;;  Here is the shorter form with define-property left out:

(defproperties header-control
 (available
   :type boolean
   :editor-type :toggle)
 (header-width
   :type positive-integer
   :reader default-header-width
   :writer (setf default-header-width)
   :editor-type :short-expression)
 (header-justification
   :type justification
   :editor-type :multiple-choice
   :reader default-header-justification
   :writer (setf default-header-justification)
   :choices :justification-values)
 (button-style
   :type boolean
   :editor-type :toggle
   :remake t)
 (on-range-change
   :type event-handler
   :editor-type :function)
 (on-set-focus
   :type event-handler
   :editor-type :function)
 )

Reader and writer examples. This includes examples of calls to defcomponent.

;; This example shows the typical case of defining properties 
;; for a standard-class, where the accessor methods that 
;; are automatically created for the size slot are also 
;; used by default as the reader and writer of the associated 
;; size property.  This technique of sharing
;; the name is recommended wherever it is feasible.

(defcomponent foo ()
  ((size :initarg :size
     :initform nil
     :accessor size))
  (:default-initargs
   :size :big)
  (:properties
   (size
    :help-string "How big it is."
    :type (member :big :medium :little nil)
    :editor-type :multiple-choice
    :choices '(:big :medium :little))))
(setq f (make-instance 'foo :size :little))
(inspect f)

;; ------------------------------------------------------
;; This example defines a property that computes its 
;; value each time it is read rather than reading a 
;; cached value from a slot.

(defcomponent yellow-item-list (single-item-list)
  ()
  (:default-initargs
   :background-color yellow)
  (:properties
   (how-many
    :read-only t)))
(defmethod how-many ((control yellow-item-list))
   (length (range control)))
(setq c (make-instance 'yellow-item-list
          :range '(a b c d)))
(inspect c)

;; -----------------------------------------------------------
;; This example does the same thing for an existing class, using
;; defproperties instead of defcomponent

(defproperties single-item-list
 (define-property how-many
   :read-only t))
(defmethod how-many ((control single-item-list))
   (length (range control)))
(setq d (make-instance 'single-item-list
          :range '(a b c d e)))
(inspect d)

;; -----------------------------------------------------------
;; This example demonstrates defining a property 
;; on a non-standard class, using an arbitrary place 
;; to hold the property values (since there is
;; no slot for the property).

(defproperties integer
    (define-property roundness))
(defparameter *integer-roundness* (make-hash-table))
(defmethod roundness ((integer integer))
   (gethash integer *integer-roundness* :unknown))
(defmethod (setf roundness)(value (integer integer))
   (setf (gethash integer *integer-roundness*) value))
(setf (roundness 6) :quite)
(inspect 5)
(inspect 6)

Properties in the Inspector

If the inspector should treat some instances of a class differently than other instances, that can be achieved by adding methods to one or more of the following generic functions: property-reader, property-writer, property-type, property-editor-type, property-choices, property-help-string, property-remake, property-read-only, and property-hidden.


delay-pop-up-menus-until-mouse-buttons-up

Generic Function, cg package

Arguments: cg-configuration

When the value of this configuration option is true, then if pop-up-menu is called while any mouse button is down, the menu will not appear until all mouse buttons have been released. The pop-up menu code does this by simply calling wait-for-mouse-buttons-up before showing the menu. When nil, there is no delay.

The default value is nil.

This option does not appear on the IDE's Options dialog, but could be set to nil programmatically with the following form:

(setf (delay-pop-up-menus-until-mouse-buttons-up
        (configuration *system*))
      nil)

delay-redraw

Generic Function, cg package

Arguments: object

Disables all drawing on object until a resume-redraw is subsequently called on the object. object may be a window or a dialog-item (control). Refer to with-delayed-redraw for more information.


delay-write-cell-value

Generic Function, cg package

Arguments: grid-widget

Returns whether grid-widget (which must be a grid-widget) will delay writing interactive user edits back to application data areas, to allow the user to either confirm or reject the changes sometime later. The value may be set by passing the delay-write-cell-value initarg at creation time, or any time later by calling (setf delay-write-cell-value). The default value is nil.

If nil, then any interactive edit to the value displayed in a grid cell will immediately call an application write-cell-value method or data-writer function to store the new value into an application data area.

If true, then a write-cell-value :around method will hold the new value internally until the application either calls write-delayed-cell-values to write all pending changes, or calls clear-delayed-cell-values to cancel all pending changes and redisplay the previous values.

Obscure note: if you (atypically) set this property to nil for an existing grid-widget that may be holding delayed values at the time, then you should probably call either write-delayed-cell-values or clear-delayed-cell-values just before that.


delayed

Generic Function, cg package

Arguments: standard-object

Returns the value of the delayed property of standard-object.

For a scroll-type control such as a horizontal-scroll-bar or a trackbar, the delayed property determines whether on-change is called to update the control's value continuously as the user drags the scroll-box or pointer along the slider, or whether it is called only once at the end of the scroll gesture.

For text controls such as an editable-text or combo-box, the delayed property determines whether on-change is called to update the control's value as each character is typed, or whether it is called only once after the user has finished typing and moves the keyboard focus from the control. If you use the the delayed property on one of those controls but you need the latest value of the control, you may have to use fetch-control-value rather than value. Examples are given in the description of fetch-control-value.

For the split-bar control, the delayed property determines whether side effects occur continuously during a drag, or only once at the end of a drag.

Here are the widgets, along with the values and the associated behaviors.

delayed is a property of the following classes:

combo-box, editable-text, horizontal-scroll-bar, multi-line-editable-text, trackbar, up-down-control, vertical-scroll-bar.


deletable

Generic Function, cg package

Arguments: grid-subsection

Returns whether the user may interactively delete the grid row or column. When the user presses the DELETE key, a list of all rows and columns that are marked as deletable and which are selected (typically by clicking the header cell) is passed to the function delete-selected-subsections. Before deletion actually occurs, confirm-grid-subsection-deletion is called (by the system) to confirm the user's intention.

deletable is a property of the grid-subsection, grid-column, row-header-column, grid-row, and column-header-row classes.


delete-class-grid-row

Function, cg package

Arguments: class-grid data-object

Removes one of the displayed objects from a class-grid. An alternative is to replace the whole set of displayed objects by calling (setf value) on the grid, passing a list of all objects to display.

Internally this removes a class-grid-body-row from the body row-section of the class-grid.

class-grid is the class-grid from which an object will be removed.

data-object is the object to remove. It should be an instance of the edited-class of the class-grid. If the object is not found in the class-grid, then nothing is done.

See also add-class-grid-row.


delete-column

Generic Function, cg package

Arguments: column

Deletes a grid-column (of a grid-widget) from its grid-column-section, removing it from the section's subsections list, and moving and/or stretching other columns in the section (depending on the proportional property of the objects) to fill the space that had been occupied by the deleted column.

See also delete-row and delete-selected-subsections.


delete-command

Generic Function, cg package

Arguments: window-or-widget

Deletes an object from the specified window or widget if possible. Does not place anything onto the clipboard as copy-command and cut-command do.

window-or-widget should an instance of the basic-pane, dialog-item, or screen class or one of their subclasses.

This function behaves as copy-command does to pass its action to a child window, except that it calls delete-selection rather than copy-selection on the child window. See copy-command for more information.

Here is the default method for windows and the screen:

(defmethod delete-command ((stream screen-stream))
  (let* ((child (selected-window stream)))
    (if* child
       then (delete-command child)
       else (delete-selection stream))))

In earlier releases, use of this operator was deprecated. It has now been restored to approved status.


delete-row

Generic Function, cg package

Arguments: row

Deletes a grid-row (of a grid-widget) from its grid-row-section, removing it from the section's subsections list, and moving and/or stretching other rows in the section (depending on the proportional property of the objects) to fill the space that had been occupied by the deleted row.

See also delete-column and delete-selected-subsections.


delete-selected-subsections

Generic Function, cg package

Arguments: grid-widget &key (confirm t)

Conditionally deletes the grid-rows and grid-columns of grid-widget (which must be an instance of grid-widget) that are both deletable and selected. If confirm is true (the default), then confirm-grid-subsection-deletion is called, and the deletion is done only if that overridable generic function returns true. If confirm is nil, then the deletion is always done. The return value is the list of subsections that were deleted; this is nil if no subsections were selected or if the user canceled the confirmation dialog.

There is a delete-selection method for grid-widgets that calls delete-selected-subsections, so an application could call either. In the IDE, the Edit | Delete command calls delete-selection, so its keyboard shortcut (the Delete key) will call this function automatically. A standalone application would need to call this function in its own way instead.

Alternately, delete-row and/or delete-column can be called to delete individual rows and columns regardless of their state, and (setf subsections) can be called to replace the whole set of rows or columns. delete-selected-subsections calls delete-row or delete-column to delete each subsection, so an application's wrapper methods on those generic functions would catch deletions that are done in either way.


delete-selection

Generic Function, cg package

Arguments: window-or-widget

Deletes the selected object (if any) in window-or-widget, if it knows how to do so for the particular window or widget. Returns true if a deletion was done, and nil otherwise.

window-or-widget should be an instance of a basic-pane subclass or a dialog-item subclass.

The default method always does nothing (and therefore returns nil). Otherwise the methods behave the same cut-selection.

See cg-clipboard.html.


deselect-all-subsections

Generic Function, cg package

Arguments: grid-widget &optional excepted-subsection invalidate-borders-p

Deselects all grid rows and columns of a grid-widget that are currently selected (see selected).

grid-widget is a grid-widget control.

excepted-subsection may be either nil or a grid-row or grid-column which is not to be deselected. This allows leaving a single row or column selected.

If invalidate-borders-p is true, then both the interiors and the borders of the deselected subsections will be redrawn, rather than the interiors only.


deselect-sections-when-lose-focus

Generic Function, cg package

Arguments: grid-widget

Returns what happens to selected grid rows and columns of grid-widget when the keyboard focus moves away from the grid.

The value can be t or nil. If nil, any selected subsections in the grid are still selected after the focus moves away from the grid-widget.

If the value is t, all grid subsections are deselected when the focus moves off the grid-widget.

deselect-sections-when-lose-focus is a property of the grid-widget class.


deselect-sections-when-move-focus

Generic Function, cg package

Arguments: grid-widget

Returns what happens to selected grid rows and columns of grid-widget when the keyboard focus moves to another subsection of the grid.

The value can be t or nil. If nil, any selected subsections in the grid are still selected after the focus moves to another cell.

If the value is t, deselects all grid subsections when the focus moves to another cell within the grid.

deselect-sections-when-move-focus is a property of the grid-widget class.


deselect-subsection

Generic Function, cg package

Arguments: grid-widget section subsection &optional invalidate-borders-p

Use of the function is deprecated. Use (setf selected) instead.

Deselects a grid row or column if it is currently selected (see select-subsection), and otherwise does nothing.

grid-widget is a grid-widget control.

section is either a column-section or a row-section.

subsection is either a grid-row or a grid-column.

If invalidate-borders-p is true, then both the interior and the border of the subsection will be redrawn, rather than the interior only.

See also deselect-all-subsections.


destroy-icon-handle

Function, cg package

Arguments: handle

This function is specific to the Windows platform, and will have no effect elsewhere. On other platforms, pixmaps can be used where icons are used on Windows.

Destroys the icon indicated by the handle argument so that the icon can no longer be drawn, freeing the associated operating system resources. It is not normally necessary to call this function, since icon resources are always freed when Lisp is exited. But if an application creates many icons, then it is possible to run out of icon resources, in which case this function should be called on icons that are no longer being used.

It is safe to call this function on an icon if all of the following are true:

handle should be an integer that was returned by a call to either extract-icon-from-file or create-icon-handle.


destroy-pixmap-handle

Generic Function, cg package

Arguments: pixmap-handle

Destroys the "device-dependent pixmap" indicated by the handle argument, freeing the associated operating system resources.

This function is largely for the backward compatible style of using separate objects for the texture, mask, texture-info, and pixmap handle of a pixmap. It is now recommended instead to use a pixmap object, which encapsulates all of these. With a pixmap object, call close-pixmap-handle (rather than this function) to cause the pixmap to stop using a handle to a device-dependent pixmap and to free up the OS resources it uses.

It is safe to call this function if the application will no longer be passing this pixmap handle (or a pixmap object that still uses it) to copy-to-stream or copy-pixels-to-stream.


development-main-window

Generic Function, cg package

Arguments: system

Returns the development-main-window of system. The current system is the value of *system*.

When the IDE is present, this function returns the main IDE window that is the owner of the various IDE tool windows. See ide:main-ide-window and ide:use-ide-parent-window. When the IDE is not present (either in a standalone Common Graphics application or in a development lisp that has loaded Common Graphics but not the IDE), this function returns the screen.

The owner argument to the function make-window defaults to the value returned by development-main-window. This means that the default owner of a window created in the IDE will be the ide:main-ide-window, so that the window will exist "within the IDE" for convenience. Otherwise the default owner of a window is the screen.

development-main-window is a property of the system class.


device

Generic Function, cg package

Arguments: form

Returns class of a window or the class to instantiate when running a form (that is, it is the accessor/setter of the class slot of a form). A form (a special window used to design actual application windows) is always an instance of the form class, to provide its special widget-editing behavior. The class property indicates the intended class that should be instantiated for the application when the form is run or the window associated with the form is created. This function accesses the class slot (since class is a Common Lisp symbol, its name is not available to be the accessor/setter).

But note that it is uncommon to need to use that function programmatically (one typically sets the class slot upon creation of a window with make-window or using the class slot in an inspector window). The form (using Common Lisp functions) (class-name (class-of object)) also serves as an accessor.

This function can also be applied to a window object which is not a form, in which case it returns what (class-name (class-of object)) would return, the class of the window.


device-bitmap

Macro, cg package

This function is no longer supported.


device-context

Generic Function, cg package

Arguments: window

Returns an integer that identifies the device-context of window if it has one, or nil otherwise. A device-context is a construct used in the Windows API to specify a set of parameters that are used when drawing on a window. A common graphics application does not normally need to deal with a window's device-context directly, but if you need to pass the window to a winapi function that calls for the window's device-context (or hDC), then you should pass the integer returned by this function for that argument. See also windows:handle, which returns the window's "handle".

Every non-control window in common graphics (and every lisp-widget window) is automatically assigned a device-context, which it keeps until it is closed. Controls supplied by the OS (all controls except lisp-widgets), on the other hand, are not automatically given device-contexts in lisp since it is normally only the OS rather than lisp that draws on the control. If you do want to draw directly on a non-lisp control, then you must give the window of the control a device-context while drawing on it. The easy way to do this is to wrap a call to with-device-context around the code that draws on the control.


device-to-dialog-units

Generic Function, cg package

Arguments: stream position-or-box

Modifies position-or-box to convert its coordinates from pixel units to "dialog units". The Windows operating system defines a dialog unit as being one-fourth a system font character width horizontally and one-eighth of a system font character height vertically. We discourage the use of dialog units since it can vary from one machine to another depending on the size of the system font implemented by each video device driver.

The stream argument is ignored.

In releases prior to 6.0, this function was named screen-to-dialog-units. The old name can be used for backward compatibility.


device-to-scaling-units

Generic Function, cg package

Arguments: stream position-or-box

Argument stream should be a cg-stream. For a stream that has the scaling-stream mixin, converts a position or box from pixel units to scaled units (destructively modifying it). For other streams, simply returns the position or box that was passed.


device-to-stream-units

Generic Function, cg package

Arguments: stream position-or-box

Converts a position or box that is in device units (directly relative to the physical interior upper left corner of the device (typically a window) specified by stream) so that it is in stream units (offset from its position relative to the physical interior upper left corner of window according to the scroll position and origin of stream).

Destructively modifies the position-or-box argument.

In earlier releases, this function was named window-to-stream-units. The old name can be used for backward compatibility.


dialog-field

Function, cg package

Arguments: dialog name

Returns the value of a control on a dialog. The dialog argument can be either a dialog object or the name of a dialog. The name argument is the name of the control (on that dialog) whose value is to be returned.

See also dialog-fields.


dialog-fields

Macro, cg package

Arguments: dialog &rest names

Returns multiple values indicating the value of each of a set of widgets on a dialog. The dialog argument can be either a dialog object or the name of a dialog. Each successive argument is the name of a widget (a member of the dialog-item class) on that dialog, whose value is to be returned as the next returned value.

See also dialog-field.


dialog-item

Generic Function, cg package

Arguments: window

Returns the dialog-item (i.e. control) associated with window, or nil if window is not the window of a dialog-item. Dialog-items (i.e. controls) are displayed in a child-window of the parent dialog. This window is typically co-extensive with the control and so is not visible as a window to users. However, certain functions operate on the window and others operate on the control. This function and the function window return the control given the window and the window given the control, respectively.


dialog-item-p

Generic Function, cg package

Arguments: x

Returns true if its argument is a dialog-item (i.e. control suitable to be placed on a dialog) and returns nil otherwise.


dialog-items

Generic Function, cg package

Arguments: basic-pane

Returns a list of dialog-items (i.e. controls) on basic-pane. This list should not be modified although a new list can be set with setf.


dialog-to-device-units

Generic Function, cg package

Arguments: stream position-or-box

Returns position-or-box after modifying it so that the dimensions are in pixel (screen) units rather than dialog units.

In releases prior to 6.0, this function was named dialog-to-screen-units. The old name can be used for backward compatibility.


dialog-to-screen-units

Generic Function, cg package

Arguments: stream position-or-box

The name of this function was changed in release 6.0 to dialog-to-device-units. See the description of that function for details. The symbol dialog-to-screen-units continues to name that function as well, for backward compatibility.


dialog-units-p

Generic Function, cg package

Arguments: dialog-item

Returns whether dialog-item's coordinates are specified in dialog-units rather than in pixels. If true, then the dialog-item's coordinates are measured in dialog-units, which are defined as one-fourth of a system-font space width wide or one-eighth of a system-font line-height high. If nil, the coordinates are in pixels, which are the coordinates that are usually used by common graphics.

Dialog-items will be created using pixel coordinates unless the :dialog-units-p initarg is passed as true when creating the dialog-item with make-instance.

Because the system-font varies from one machine to the next, using dialog-units is discouraged.


dialogp

Generic Function, cg package

Arguments: x

Returns true if its argument is an instance of class dialog and returns nil otherwise.


digit-char-or-space-p

Function, cg package

Arguments: character

Returns true if either digit-char-p returns true for the specified character or the character is a space.

character should be a character. Otherwise it is an error.

This function is handy as a predicate function in the *template-chars* association list, to allow the user to type either a numeral or a space at a certain position.


digitizer-capabilities

function, cg package

Arguments:

Returns a list of zero or more of the keyword symbols shown below, indicating the capabilities of the computer's touch input device, if it has one. nil will be returned if there is no touch input device.

Here are Microsoft's explanations of the capabilities. Apparently integrated means built into the computer (such as its screen) while external means connected to it (such as a tablet). Multiple inputs refers to multiple simultaneous fingers (or pens).

See also the touch-point class and About Touch Gesture Support in Common Graphics on Windows in cgide.html.


digitizer-is-ready

function, cg package

Arguments:

Returns true if the computer has a touch input device that is currently enabled and working, and nil otherwise. This is the same as the :ready indicator returned by digitizer-capabilities.

See also the touch-point class and About Touch Gesture Support in Common Graphics on Windows in cgide.html.


direction-of-increase

Generic Function, cg package

Arguments: scroll-bar-mixin

Returns the value of the direction-of-increase property of the argument. The value of this property can be :up or :down. It indicates the direction a vertical scroll bar bubble or trackbar pointer moves when the value of the scroll-bar/trackbar increases. :up and :down are also used for horizontal scroll bars, with :up meaning to the left and :down meaning to the right.

direction-of-increase is a property of the trackbar, horizontal-scroll-bar, and vertical-scroll-bar classes.


disable-visual-styles

Generic Function, cg package

Arguments: dialog-item

Returns whether Microsoft Visual Styles is disabled for a particular widget, identified by the dialog-item argument. (This widget property has no effect on non-Windows platforms.) The value may be set at creation time by passing the disable-visual-styles initarg, or any time later by calling (setf disable-visual-styles).

The value should be true to disable the usual Visual Styles effects for the widget, or nil to use Visual styles for it as usual. The default value is nil.

Visual Styles reflect the current theme that the user has chosen for their whole Windows environment. Sometimes this theme can override a property of a widget, such as its background-color. To stop that from happening, you can set the disable-visual-styles property of the widget to true, though this may result in a generally plainer style for that widget.


discard-pending-events

Function, cg package

Arguments:

Discards all events (except repaint messages) from the OS that are currently queued up, so that they are never handled. Repaint messages are handled rather than discarded.


display-controls

Generic Function, cg package

Arguments: media-player

Returns whether the :display-controls initarg was passed as true to make-instance when creating an audio-player or video-player widget. Calling the setf of this function will have no effect; the value must be passed as an initarg at creation time.


display-html

Generic Function, cg package

Arguments: html-widget-or-browser uri-or-path

Displays a web page or an HTML or plain text file in an html-widget. Alternately you can set the value property of the html-widget.

html-widget-or-browser should be either an html-widget or an html-browser. When a browser is specified, it sets the value of the html-widget that's in the browser dialog.

uri-or-path should be either the URL of a web page (a string) or the pathname or path namestring of a file that contains HTML or plain text.

As a special case, a post can be done by passing the uri-or-path argument as a plist that contains the keys :uri and :post-string. The :uri value should be a URI as usual and the :post-string value should be the string to post, as in (:uri "http://foo.com" :post-string "The string to post.").

See the html-widget control.


display-instance

Generic Function, cg package

Arguments: object-editor instance &key no-save-current

This is the general function for displaying an arbitrary object in an object-editor dialog. To instead display the first, last, next, or previous instance of the dialog's sorted list of instances, display-special-instance may be called instead.

object-editor is the object-editor that will display the object.

instance is the object to display. It should be an instance of the edited-class of the object-editor.

If no-save-current is nil, as it is by default, then object-editor-save will be automatically called to save any user modifications to the currently-displayed instance before displaying the new instance. If true, then this is not done, and so any edits to the current-instance are discarded.


display-pixmap-in-browser-tab

Function, cg package

Arguments: pixmap &key surrounding-color title

Displays the specified pixmap in a new web browser tab. This function should only be called if js-mode indicates that CG is running in CG/JS mode. surrounding-color, if not nil, should be an RGB object (see make-rgb) for the background-color that will surround the pixmap in the new tab. title, if not nil, should be a string to display in the small rectangle above the tab interior (which the user clicks to select that tab).

The new browser tab is not a CG tab, so the user could right-click the image and select the browser's standard "Save Image to File" command to save the pixmap to a file on the client machine. (The CG function save-pixmap saves a file on the server machine.)


display-special-instance

Generic Function, cg package

Arguments: object-editor type

Displays the first, last, next, or previous instance of an object-editor dialog's sorted list of edited-instances. To display some other instance, call display-instance instead.

The sorted list that determines which instance is displayed is an internally cached list and not the official list of instances in the edited-instances property, if any. See primary-name-slot.

Four of the built-in command-buttons may be used to call this function, or it can be called in some other way. An application could add wrapper methods to catch whenever an object-editor displays an instance.

object-editor is the object-editor that will display the instance.

type should be one of the keywords:


displaying-on-mac

Function, cg package

Arguments:

Returns true if the user is on a Mac, or nil otherwise.

In CG/JS mode (and thus always on the Mac and Linux), the returned value reflects the platform where the web browser is running, rather than where the CG lisp application is running, which may be different when the CG app is running in server mode.

This function may be convenient when defining the event-synonym of a menu-item, when the keychords are different on the Mac (such as by employing the Command key, which is called meta-key in CG). Otherwise each such case would need to use the functions js-mode and web-browser-os along with #+macosx and #-macosx conditionalizations to determine the proper key to use in every case. This function does that for you. For example:

   (make-instance 'menu-item
     :value 'reload
     :title "~Reload"
     :event-synonym (cond ((displaying-on-mac) '(meta-key #\R))
                          (t '(control-key alt-key #\R))))

do-click

Generic Function, cg package

Arguments: window-or-widget-or-nil &key (position (and window-or-widget-or-nil :center)) (mouse-button :left) (pre-expose t) (preview-seconds 0.5)(down-seconds 0.5)

This generic function is specific to Microsoft Windows, and should not be called on other platforms.

This generic function programmatically emulates clicking a mouse button, after optionally exposing a window and/or moving the mouse cursor over it. This may be useful for automated testing.

window-or-widget-or-nil may be either a window, a dialog-item, or nil. If this argument is non-nil and pre-expose is true, then the specified window or widget and all of its ancestor windows are selected so that the window or widget is in front to receive the mouse click. The position argument will also be relative to this window or widget.

The keyword arguments are:

Examples

;; Left-click at the center of a window's scrollable page.
(do-click some-window)

;; Left-click near the upper-right corner of its scrollable page.
(do-click some-window
  :position (make-position (- (interior-width some-window) 8)
                           12))

;; Left-click it with no pause for people to watch the action.
(do-click some-window :preview-seconds nil :down-seconds nil)

;; Right-click in the center of a window's scrollable page.
(do-click some-window :button :right)

;; Left-click whatever is under the mouse.
(do-click nil)

;; Left-click an arbitary position on the screen.
(do-click nil :position (make-position 100 200))

;; Left-click over the center of a window, but without
;; first exposing it.  So if another window covers it, then the
;; click will go to that window instead.  Pre-expose defaults to
;; t to ensure that the click goes to the specified window, but
;; it may be useful to pass it as nil as in this example if you
;; are testing that the window is exposed when it should be.
(do-click some-window :pre-expose nil)

do-default-debugable-restart

Function, cg package

Arguments:

This function is never invoked directly by the user. It can be specified as the value of the ide:on-restart property for a project so that when a project EXE is created and the EXE is started, the Allegro CL console appears with instructions displayed on what function(s) to call to continue the EXE initialization. At that point, the console is just a lisp listener so you can evaluate arbitrary functions to set/determine the initial environment of the EXE while debugging. You can even wrap the functions displayed by the instructions in a call to process-run-function so that the console listener remains active while the application is running.


do-default-restart

Function, cg package

Arguments:

This symbol is the default value of the ide:on-restart property of a project. See ide:on-restart for more information. (In earlier releases, this function took a console-state keyword argument.)


do-keypress

Generic Function, cg package

Arguments: window-or-widget-or-handle-or-nil keynum-or-character &key (preview-seconds 0.5)(down-seconds 0.5) shift control alt (down t)(up t)

This generic function is specific to Microsoft Windows, and should not be called on other platforms.

This generic function programmatically emulates pressing and/or releasing a key on the keyboard, after optionally exposing a window and giving it the keyboard focus. This may be useful for automated testing.

The two required arguments window-or-widget-or-handle-or-nil and keynum-or-character.

window-or-widget-or-handle-or-nil may be either a window, a dialog-item, an internal window "handle", or nil. If non-nil, then the specified window or widget and all of its ancestor windows are brought to front, and the window is given the keyboard focus before the keypress is done, so that the specified window will receive it. (If a handle of a window in another application is specified, then it is not possible to give it the keyboard focus programmatically, though do-click can work for that.)

keynum-or-character indicates which key to press and/or release. It may be either the value of one of the "vk-" key constants (see key-names) or the character that appears on one of the alphanumeric keys. If an uppercase character is passed, then a shift is done as if shift were true.

The keyword arguments are:

Examples

;; Type a "j" to a window.
(do-keypress some-window #\j)

;; Type a semicolon to whatever window has the keyboard focus.
(do-keypress nil vk-semicolon)

;; Press down the shift key without releasing it.
;; WARNING:  Doing this without a subsequent
;; up-click of the same key leaves the OS thinking
;; that the shift key is still down, and a further keystroke
;; will believe it is shifted.  This can be fixed interactively
;; by simply pressing and releasing the left shift key.
(do-keypress some-window vk-shift :up nil)

;; Type control-j into a window.
(do-keypress some-window #\j :control t)

do-keypresses

Generic Function, cg package

Arguments: window-or-widget-or-handle-or-nil object &key (preview-seconds 0.5) (down-seconds 0.5)

This generic function is specific to Microsoft Windows, and should not be called on other platforms.

Calls do-keypress once for each character in a string.

window-or-widget-or-handle-or-nil may be either a window, a dialog-item, an internal window "handle", or nil. This is passed as the window-or-widget-or-handle-or-nil argument to do-keypress.

If object is a string, it is used directly. If it is a symbol, its symbol-name is used as the string. Otherwise a string obtained by calling princ-to-string on object.

The preview-seconds keyword argument to do-keypress will be the preview-seconds to do-keypresses for the first character and as nil for all other characters.

The down-seconds keyword argument to do-keypress will be the down-seconds keyword argument to do-keypresses for the last character and as nil for all other characters.

Examples

;; Type a whole string of characters into a window.
(do-keypresses some-window "How about that.")

;; Print an arbitrary object into whatever window has the keyboard
;; focus.
(do-keypresses nil (list :one "Foo"))

do-windows

Macro, cg package

Arguments: (child parent-stream &key result owned-p states) &rest forms

Executes forms (the body) once for each child window of parent-stream, or for each non-child owned window of parent-stream if owned-p is true. child should be a symbol that will be bound to each child (or non-child owned window) during the execution of forms. The value of result is returned from do-windows. This macro avoids consing a list of the windows as the function windows would do, and so may be more efficient in tight loops.

parent-stream may be either a window or the screen. The screen is the value returned by (screen *system*). See screen and *system*.

states may be either nil or a list of any of the window state symbols, :normal, :maximized, :icon, or :shrunk. If states is such a (non-empty) list, then the forms are executed only for windows that are in one of those states. If states is nil, then the forms are executed for all of the windows.

Example

The following form will print the names of all of the top-level windows that are in :normal state (see screen and *system*).

(do-windows (child (screen *system*) :states '(:normal))
  (print (name child)))

double-buffered

Generic Function, cg package

Arguments: window-or-lisp-widget

Returns whether a window or a lisp-widget uses a memory bitmap to reduce flashing effects when the window is redisplayed. The value may be set either by calling (setf double-buffered) or by passing the :double-buffered initarg when using make-window to create the window or make-instance to create the lisp-widget.

window-or-lisp-widget should be either an instance of basic-pane or one of its subclasses, or an instance of lisp-widget or one of its subclasses. The value should be true to put the window into double-buffering mode, or nil to take it out of double-buffering mode. The default value is nil except for outline and grid-widget, where the default is t.

Double-buffering works by redirecting all drawing function calls to actually draw on the window's internal memory bitmap, and later copying the memory bitmap to the visible window in a single operation. This typically eliminates the flash that occurs when a window is first blanked out before redrawing its content. This flash is often noticable when the user interactively scrolls or resizes a window, or when the application programmatically updates the contents of a window for animation effects.

Drawing is redirected to the memory bitmap only when a drawing function is called inside a redisplay-window method that was called by Common Graphics (rather than the application calling it directly), or when the drawing function is called inside a with-double-buffering macro call. When an application updates the contents of a window, it normally should call invalidate on the window to trigger a redisplay (and then perhaps update-window to force the redisplay to happen immediately), and then Common Graphics will call the window's redisplay-window method. But if you really need to draw directly to a window and would still like double-buffering to occur, then this can be achieved by doing the drawing inside a call to with-double-buffering.

The double-buffered property may not be applied to os-widgets because Common Graphics does not have control over the drawing of them. In addition, the bitmap-pane window and the drawable and multi-picture-button lisp-widgets implement special types of double-buffering, and so this general double-buffering facility may not be used with instances of those classes. (If you do turn the double-buffered property on for them, a warning is signaled and the request is ignored.)

The double-buffered property will automatically create a memory bitmap that is the size of the window's interior, and replace it with a larger one when needed. A bitmap-pane, by contrast, creates a memory bitmap that is the size of the entire scrollable page (or canvas) of the window. So a bitmap-pane is more expensive in terms of memory usage, but will also remember an entire drawing so that the application does not need to redraw it at all when the window is exposed or scrolled.

Creating or resizing a double-buffered window could signal an error of type memory-bitmap-not-created if there is not enough memory for the memory bitmap.

Example

There is a complete code example of using the double-buffered property for animation in the section Animation in cg-drawing.html.


double-click-as-default-button

Function, cg package

Arguments: dialog item

This is a possible value for the on-double-click event handler for a control on a dialog with a default-button. It tries to make double-clicking on the control have the same effect as clicking on the default-button. It does this by causing the on-change handler of the default-button to run.

The dialog argument is the dialog and the item argument is the control but this function is not typically called directly.


double-click-event

Generic Function, cg package

Arguments: dialog widget

This function is called whenever a double left click is done on a control that implements double-clicks. The default method calls the on-double-click event-handler function of the control if it has one.

Double-click behavior could be specified for a whole control subclass by adding a double-click-event method rather than giving the same on-double-click event-handler function to every instance of the class.


double-click-time

Generic Function, cg package

Arguments: stream

Returns the double click time for stream in internal time units. The double-click time is the maximum time between clicks for two clicks to be considered a double click rather than two single clicks.


double-sided

Generic Function, cg package

Arguments: printer

Returns the double-sided property of printer. This property of a printer stream may be specified only as the value of the :double-sided initarg to open-stream. See pop-up-printer-job-dialog for the possible values of this option.


down-key-names

Function, cg package

Arguments:

Returns a list of names indicating the keyboard keys and mouse buttons that were in a pressed-down state when the event that is currently being handled occurred. Each name is either the lisp character shown on a key or one of the "vk-..." constants that are the value of the constant key-names.

This function operates per-thread. Specifically, keypresses that are done while a window that was created in a particular thread has the keyboard focus will not be included in the list returned by a call that is made to down-key-names in any other thread. (An exception is that if there is a single window hierarchy that contains windows from both threads, then the operating system appears to combine the event queues of the two threads, and down-key-names will still include the keys that were pressed in a window of the other thread.)

Compatibility note: Through version 6.0, the returned list did not include elements for the keys associated with lisp characters, and included only the vk-... symbols. This was not particularly useful, as it indicated what some but not all the pressed keys were. All keys on standard PC keyboards should now be covered.

See also down-keys, key-is-down-p, key-was-down-p, and mouse-button-state.


down-keys

Function, cg package

Arguments:

Returns a list of integers indicating the keyboard keys and mouse buttons that were in a pressed-down state when the event that is currently being handled occurred. Each integer is either the char-code of the character shown on a key (thus, (char-code #\A) for the A key) or the value of one of the "vk-..." constants that are the value of the constant key-names.

This function operates per-thread. Specifically, keypresses that are done while a window that was created in a particular thread has the keyboard focus will not be included in the list returned by a call that is made to down-keys in any other thread. (An exception is that if there is a single window hierarchy that contains windows from both threads, then the operating system appears to combine the event queues of the two threads, and down-keys will still include the keys that were pressed in a window of the other thread.)

See also down-key-names, key-is-down-p, key-was-down-p, and mouse-button-state.


drag-and-drop

Generic Function, cg package

Arguments: widget &key move-values

This operator was modified in release 11.0 by the addition of the move-values argument.

Initiates a dragging operation from widget. The user may "drop" onto another control by clicking the mouse to associate the two controls together in some way. The drag continues until the user "drops" by either pressing a mouse button (if no mouse buttons were down when drag-and-drop was called), releasing a mouse button (if a mouse button was down when drag-and-drop was called), or pressing ESCAPE to cancel the drag. During this time, the mouse cursor changes to indicate whether a drop is allowed at the current mouse cursor location. A drop is allowed whenever the mouse cursor is over a control where droppable-p returns true when called on the dragged control and that dropped-onto control. When the drop is done on the dragged widget, then both droppable-p and droppable-onto-self must return true to allow the drop. The default droppable-p method returns whether the drop-sources property of the dropped-on widget indicates that the drop should be allowed. So an application can enable dragging and dropping either by supplying drop-sources properties or by adding droppable-p methods. By convention, drag-and-drop should not be called for a particular control if

(draggable-p control)

returns nil. The default draggable-p method returns true for any control. If the user drops where a drop is allowed, then good-drop is called; if the user drops elsewhere, then bad-drop is called; if the user cancels by pressing ESCAPE, then neither function is called.
The default good-drop method calls drop-put to perform the drop. The built-in drop-put methods typically copy a value from the dragged-from widget to the dropped-on widget, but an application could add drop-put methods for custom dropping behavior. An application will typically add draggable-p methods to determine which controls may be dragged from, droppable-p methods to determine which controls may be dropped onto which, and good-drop methods to process successful drops. drag-and-drop-mouse-moved methods could be added to trigger side effects as the user drags the mouse cursor.

drag-and-drop returns the control that was dropped onto if any, or nil otherwise. There is no dropped-onto control if the user either cancels the drag by pressing ESCAPE or drops at a location that is not over any control. If the dropped-on widget is an item-list widget (and no custom methods are overriding the built-in methods), then the dropped value will be added as a choice in the range of the dropped-on widget, or as multiple choices when the dropped value is a list. And if the move-values argument is true and the dragged-from widget is also an item-list, then the dropped values will also be removed from the range of the dragged-from widget, to effectively move the values rather than copy them. By default, the only visual indication that a drag is taking place is the changing mouse cursor. This is the standard drag-and-drop approach in Windows. But if

(drag-images (configuration *system*))

is set to true, then an attempt is made to drag an image of some part of the dragged-from control. (See configuration, *system*, and drag-images.) This image is obtained by calling box-to-drag on the dragged-from control and copying pixels from the screen for that section of the control. box-to-drag methods are supplied for most of the controls to specify the area occupied by the currently selected value of the control. Note that this approach will not work well if the current value of the control is ever scrolled out of view. Depending on which types of controls are being dragged from, these images may or may not be considered sufficiently aesthetic for an application's interface, and so this dragging option should not be used if the result is unsatisfactory. When the IDE is running, a general mouse-left-down method (shown below) causes drag-and-drop to be called if the Alt key is held down and a left click and drag is done on a control. A droppable-p method for the inspector allows dropping arbitrary values from arbitrary controls into inspector slots, and a droppable-p method specializing on both the main IDE toolbar and the extended IDE toolbar allows dragging commands between or within these toolbars. Other than these cases, the IDE does not make use of drag-and-drop, and the methods described in this paragraph exist in the IDE only. Applications must define their own gestures to call drag-and-drop, as well as their own droppable-p methods to define where drops are allowed. The following code implements the IDE's mouse-left-down method for initiating drags. It checks to see if the alt-key is down (but not the control-key or shift-key) and if the mouse cursor was in the interior area of the widget that was clicked. If so, it then initiates a drag, and otherwise it calls the next method.

(defmethod mouse-left-down ((widget dialog-item)
                            buttons cursor-position)
  ;; This method exists in the IDE to allow initiating drags
  ;; by alt-clicking any widget.
  (with-boxes (box1)
    (case (logand buttons #.(logior control-key shift-key alt-key))
      (#.alt-key
       (when (and (draggable-p widget)
                  (inside-box-p cursor-position
                                (nvisible-box (window widget) box1)))
         (drag-and-drop widget)))
      (t (call-next-method)))))

Applications can add similar methods to initiate drags. Note that while a simple left click could alternately be used to initiate a drag, this should not be done for certain widgets where a mouse-left-down always waits for a mouse-left-up to complete a value selection gesture, since the mouse will not be in a meaningful position for this when the user finally releases the mouse button after dragging; this constraint appears to be limited to the single-item-list and multi-item-list widgets. See also wait-for-drag for another way to decide whether to initiate a drag.


drag-and-drop-mouse-moved

Generic Function, cg package

Arguments: drag-widget object-under-mouse screen-position object-position

This function is called each time the mouse cursor moves during a call to drag-and-drop. The default method does nothing, but an application could add methods if it needs to trigger arbitrary side effects as the user moves the mouse. One example might be to scroll a window in which a drag is intended to be confined if the user moves the mouse outside of that window.

drag-widget is the widget that is being dragged.

object-under-mouse is the widget or window that is currently under the mouse cursor, if any, and nil otherwise.

screen-position is the current mouse cursor position in screen coordinates.

object-position is the current mouse cursor position in the coordinate system of the object-under-mouse if it is non-nil, and otherwise is nil.


drag-cursor

Generic Function, cg package

Arguments: dialog-item

Returns the mouse cursor image to be used while doing a drag from dialog-item while the mouse cursor is not over a dialog-item. (This cursor is also shown before the mouse cursor first moves off of the widget from which dragging is being done.)

An application typically would not need to call this generic function, but may define methods on it to customize the mouse cursors that are used by drag-and-drop. The returned value should be either an instance of the cursor class or a mouse cursor handle.

The default method returns the mouse cursor handle which is the value of the variable no-drop-cursor. This cursor shows a red circle with a diagonal line through it, indicating that it is generally not possible to drop when not over a dialog-item.

drop-cursor and no-drop-cursor return mouse cursors suitable for use during a drag.


drag-images

Generic Function, cg package

Arguments: configuration

When doing a drag-and-drop, the image of what is being dragged can move with the mouse, or not, as this property of configuration is true or nil. The current configuration is the value of (configuration *system*) (see configuration and *system*).

drag-images is a property of the configuration class.


drag-on-alt-click

Generic Function, cg package

Arguments: dialog-item

When this widget property is true, a drag-and-drop will be initiated from the widget whenever the user holds down the Alt key while left-clicking the widget. This is a quick alternative to writing custom code that makes a command or gesture call drag-and-drop. (The generic function draggable-p must also return true, though the default method always does that.)

There are some special considerations when the widget is an item-list, that is a single-item-list or a multi-item-list. The Alt+LeftClick will not select the clicked value before initiating the drag, mainly because in a multi-item-list that would deselect multiple values that had been selected for dragging. So the user must first select the value(s) to drag, and then do the Alt+LeftClick to do the drag. (Using the Alt key allows the Control and Shift keys to still work for selecting or toggling multiple values as usual.) If the Control key is used along with the Alt key and a successful drop is done into another item-list, then the values will be removed from this widget at the end, thereby moving the values from this widget to the dropped-on widget rather than copying them.

In the IDE, a mouse-left-down :around method makes an Alt+LeftClick on any widget call drag-and-drop. So you would not need to set this property to true when testing a project in the IDE (except for the special Control+Alt+LeftClick case), but you would need it in a standalone application that you generate from a project.


draggable-headers

Generic Function, cg package

Arguments: list-view

This property has an effect only on the Windows platform, where it is provided by the underlying Microsoft control.

Returns the value of the draggable-headers property of a list-view control. The value may be set at creation time by passing the :draggable-headers initarg to make-instance, or any time later by calling (setf draggable-headers).

This property specifies whether the user can drag list-view column headers horizontally to change their order. The value can be nil or true. The default is nil.


draggable-p

Generic Function, cg package

Arguments: drag-from-widget

Should return true if drag-from-widget can be dragged. (The default method does and other added methods should behave that way as well.)

The default method allows for dragging from any control. You may want to redefine this default method to return nil and then add specific methods to return t where dragging is allowed.


dragging-thickness

Generic Function, cg package

Arguments: split-bar

Returns the dragging-thickness property of a split-bar widget. The value may be set at creation time by passing the :dragging-thickness initarg to make-instance, or any time later by call (setf dragging-thickness).

This is the visible thickness of the split-bar widget while it is being dragged, measured in pixels. The value should be a non-negative integer. The default value is 3, to draw a dragging line that's thinner than the mouseable thickness. The value may be set at creation time by passing the :dragging-thickness initarg to make-instance, or any time later by call (setf dragging-thickness).

The mouseable thickness is specified with the bar-thickness property.


draw-arrowhead

Function, cg package

Arguments: stream from-pos to-pos &key (length 20) (width 10) fill

draw-arrowhead draws a simple arrowhead at to-pos for a line that was drawn between from-pos and to-pos.

The returned values indicate the point on the line at the base of the arrowhead. This could be used to draw the associated line so that it ends at this point instead of at the tip of the arrowhead, in order to leave a sharper tip when the line is thick. There are two returned values, for the x and y coordinates or the point.

While you can draw the line first and then draw arrowheads at one or both ends, you can also draw the arrowheads first, capturning the base coordinates and then draw the line with one end the base coordinates and thus ensure the tip of the arrowhead is sharp.

The arguments are:

Example

Here is an example function that draws arrows at various angles.

(defun test-arrowheads (&key (length 20)(width 10))
  (let* ((window (make-window :arrows
                   :class 'bitmap-window
                   :title "Arrowheads"
                   :interior (make-box 200 200 600 600)
                   :scrollbars nil))
         (pane (frame-child window))
         (center #.(make-position 200 200))
         coord side)
    (with-positions (pos1)
      (dotimes (j 9)
        (setq coord (+ 200 (* 40 (- j 4))))
        (dolist (fill (list nil t))
          (setq side (if fill 360 40))
          (nmake-position pos1 side coord)
          (draw-line pane center pos1)
          (draw-arrowhead pane center pos1 :fill fill
                          :length length :width width)
          (nmake-position pos1 coord side)
          (draw-line pane center pos1)
          (draw-arrowhead pane center pos1 :fill fill
                          :length length :width width))))))

See also cg-drawing.html.


draw-at-dragging-thickness

Generic Function, cg package

Arguments: split-bar

Returns the draw-at-dragging-thickness property of a split-bar widget. The value may be set at creation time by passing the :draw-at-dragging-thickness initarg to make-instance, or any time later by call (setf draw-at-dragging-thickness).

This property indicates whether to draw the split-bar at the typically thinner dragging-thickness even when the split-bar is idle and it has a thicker mousable area (see bar-thickness). The value should be nil or true. The default value is nil. The value may be set at creation time by passing the :draw-at-dragging-thickness initarg to make-instance, or any time later by call (setf draw-at-dragging-thickness).


draw-bezier-curve

Generic Function, cg package

Arguments: stream vertices

The function was named draw-curve is releases prior to 8.0. The new name is more descriptive and less likely to conflict with a user function name. The behavior has not changed.

Draws one or more Bezier curves on stream. vertices should be a sequence (list or vector) of positions (see make-position) that indicate the starting, ending, and control points for the curves. Each curve is specified by four positions that indicate a starting point, two control points, and an ending point in that order. The ending point of each curve is re-used as the starting point of the next curve, and so vertices must contain (1+ (* 3 N)) to draw N curves (where N must be at least 1). For example, to draw two connected curves you need to pass a sequence of 7 positions, where positions 1 through 4 specify the first curve and positions 4 through 7 specify the second.

stream should be a cg-stream.

See also cg-drawing.html.


draw-box

Generic Function, cg package

Arguments: stream box

Draws box on stream. box must be a box object, such as created by make-box. stream should be a graphical-stream.

To use individual coordinates rather than creating position objects, see draw-box-x-y.

See also erase-box and cg-drawing.html.


draw-box-x-y

Generic Function, cg package

Arguments: stream left top right bottom

Draws a rectangle on stream from an upper-left position at (left, top) to a lower-right position at (right, bottom). stream should be a graphical stream. The other arguments should be integers. To use a box object rather than individaul coordinates, see draw-box.


draw-by

Generic Function, cg package

Arguments: stream offset

Draws on stream a line from the current position to the position offset away from current position. offset should be a position (see make-position). stream should be a graphical-stream.

Contrast with draw-to and draw-to-x-y which draw from the current position to the argument location.

To use individual coordinates rather than creating position objects, see draw-by-x-y.

See also cg-drawing.html.


draw-by-x-y

Generic Function, cg package

Arguments: stream x y

Draws a line from the current position in stream to a position that is x pixels to the right of the current position and y pixels downward from the current position. stream should be a graphical-stream. x and y should be integers. To use a position object rather than individual coordinates, see draw-by.

The current position may be set by calling move-to-x-y.


draw-cell

Generic Function, cg package

Arguments: row column row-num column-num cell-box stream

Called for drawing the interior of each individual cell of a grid (see grid-widget class). If not using one of the built-in widget column types, then supply a draw-cell method to draw your custom cell. cell-box is the region within stream that contains the interior of the cell, so you should draw only within that area of stream.

Here is the default method, which is used for any cell not handled either by one of the special built-in grid-column types such as combo-box-column-mixin or by an application-defined draw-cell method. It simply draws the printed representation of the cell's value. Note that it calls read-cell-value to find the value to draw for this particular cell; this is the suggested approach, though the draw-cell method may determine what to draw by whatever means is suitable to the application. The default mthod calls cell-horizontal-padding, cell-vertical-padding, cell-horizontal-justification, cell-vertical-justification, cell-wrapped-p, data-read-converter, draw-string-in-box, inflate-box, and read-cell-value.

(defmethod draw-cell ((row grid-row)(column grid-column)
                      row-num column-num cell-box stream)
  (let* ((converter (or (data-read-converter column) #'identity))
         (value (funcall converter
                         (read-cell-value
                          row column row-num column-num))))
    (when value
      (draw-string-in-box
       stream (princ-to-string value) nil nil
       (inflate-box cell-box
                    (- (cell-horizontal-padding row column))
                    (- (cell-vertical-padding row column)))
       (cell-horizontal-justification row column)
       (cell-vertical-justification row column)
       nil (cell-wrapped-p row column)))))

Common Graphics will call draw-cell any time a grid cell gets partly uncovered or is invalidated (such as by calling invalidate-cell or invalidate-section), so an application need not call it.

A draw-cell method often calls read-cell-value to retrieve the value that should be displayed in the cell. Otherwise it may call the data-reader of the column and/or directly access the data-object of the row to find the value. Those techniques are handy if the grid follows the common paradigm where each grid row represents a data object and each grid column represents an attribute of those objects. Otherwise, a draw-cell method may use a completely custom technique for determining the value to draw, keying in some way off of the names or types of the row and column or the sub-row and sub-column indices.

Even if you are not using the built-in cell widgets such as those provided by editable-text-column-mixin or combo-box-column-mixin, you still likely won't need to write custom draw-cell methods for cells that simply display a string for the value you are returning from a read-cell-value method. And if you need to modify the way in which the default draw-cell method draws the string, you can alternately do that by writing methods on generic functions such as cell-background-color, cell-font, and cell-vertical-padding.

Before Common Graphics calls draw-cell, it will first set the current font of the stream to be the font that's returned by cell-font. It will also set the current foreground-color and background-color of the stream to be the values returned by cell-foreground-color and cell-background-color, and fill the cell with the background color. So a custom draw-cell method does not need to handle those aspects of the drawing.

See also draw-cell-focus.


draw-cell-focus

Generic Function, cg package

Arguments: grid-row grid-column stream cell-box

Draws something in a grid cell to indicate that that cell currently has the keyboard focus (and so a keypress will result in a call to cell-key-down for that row and column). The default method draws a one-pixel thick line at the outer edge of the cell's interior.

Applications should not call this function, which is called automatically, but may add methods to override the default focus drawing style.

This function is called once to draw the focus and again in the same way to erase it. The paint-operation of the stream is always temporarily set to po-invert when draw-cell-focus is called, so that drawing the same thing a second time will erase what was drawn. This means that a draw-cell-focus method should never set the paint-operation to something else, as this would prevent the erasure from working. It is also probably not useful to set the foreground-color in a draw-cell-focus method, as it is not feasible to predict the color that will result when the official foreground color is combined with the current screen colors via the po-invert operation.

grid-row and grid-column indicate the cell in which focus is to be drawn. stream is the stream on which the drawing should be done, and cell-box is the box on stream that encompasses the interior of the cell. The method may modify the box if desired. A draw-cell-focus method may draw outside this box, but the clipping-box of stream is set to the grid section that contains the cell when this function is called, so that any drawing outside the whole section will be clipped.

Here is the default method:

(defmethod draw-cell-focus ((row grid-row)(column grid-column)
                            stream cell-box)
  (decf (box-right cell-box))
  (decf (box-bottom cell-box))
  (with-line-width (stream 1)
    (draw-box stream cell-box)))

See also draw-cell.


draw-circle

Generic Function, cg package

Arguments: stream center radius

Draws a circle with the radius and center specified on stream stream should be a cg-stream. center must be a position (see make-position).

See also erase-circle.

See also cg-drawing.html.


draw-circle-arc

Generic Function, cg package

Arguments: stream center radius start-angle length-angle

Draws on stream a circle-arc, starting at start-angle and subtending length-angle, with the radius and center as specified.

Angles are measured clockwise starting from the positive x-axis (taking the center as the origin). Thus start-angle 0 is the due East point if the circle is thought of as a compass. start-angle 0 and length-angle 90 draws the arc from due East to due South. The endpoint coordinates may be determined by calling ellipse-start-and-end.

center should be a position (see make-position). stream should be a cg-stream.

See also erase-circle-arc.

See also cg-drawing.html.


draw-circle-sector

Generic Function, cg package

Arguments: stream center radius start-angle length-angle

Draws on stream a circle-sector, that is an arc and the bounding radii to produce a shape like a piece of pie, starting at start-angle and subtending length-angle, with the radius and center as specified.

center must be a position (see make-position). stream should be a cg-stream.

Angles are measured clockwise starting from the positive x-axis (taking the center as the origin). Thus start-angle 0 is the due East point if the circle is thought of as a compass. Start-angle 0 and length-angle 90 draws the lower right quarter, now thinking of the circle as a pie. The endpoint coordinates may be determined by calling ellipse-start-and-end.

See erase-circle-sector.

See also cg-drawing.html.


draw-ellipse

Generic Function, cg package

Arguments: stream center semi-major-axis semi-minor-axis semi-major-axis-angle

Draws an ellipse on stream. The ellipse is defined by the center (a position) and the two half-axes, lengths from the center to the farthest point on the edge and to the nearest point on the edge, called the semi-major-axis and the semi-minor-axis. (Technically, the major axis should be longer than the minor axis but the two arguments need not have that relationship.) Because the Windows ellipse drawer can only draw ellipses that are vertically or horizontally oriented, the semi-major-axis-angle argument must be a multiple of 90. Other values will signal an error. The argument specifies the angle between the semi-major-axis and a line parallel to the x-axis passing through the center. Angles are measured clockwise.

center should be a position (see make-position). stream should be a cg-stream.

The following example creates a window that draws a thin vertically-oriented ellipse that is 200 pixels tall and has a line-width of 3 pixels:

(defclass ellipse-window (frame-window)()
  (:default-initargs
   :exterior (make-box-relative 100 100 100 400)
   :title "Ellipse"))

(defmethod redisplay-window ((window ellipse-window) 
                             &optional clipping-box)
  (declare (ignore clipping-box))
  (call-next-method)   ;; Draw the background
  (with-line-width (window 3)
    (draw-ellipse window (make-position 50 150) 100 20 90)))

(make-window :ellipse-example :class 'ellipse-window)

See also cg-drawing.html.


draw-ellipse-arc

Generic Function, cg package

Arguments: stream center semi-major-axis semi-minor-axis semi-major-axis-angle start-angle length-angle

Draws an ellipse arc on stream. The ellipse is defined by the center (a position) and the two half-axes, lengths from the center to the farthest point on the edge and to the nearest point on the edge, called the semi-major-axis and the semi-minor-axis. (Technically, the major axis should be longer than the minor axis but the two arguments need not have that relationship.) Because the Windows ellipse drawer can only draw ellipses that are vertically or horizontally oriented, the semi-major-axis-angle argument must be a multiple of 90. Other values will signal an error. The argument specifies the angle between the semi-major-axis and a line parallel to the x-axis passing through the center.

Angles are measured in degrees clockwise from the 3 o'clock position. The endpoint coordinates may be determined by calling ellipse-start-and-end.

So, the ellipse created when specifying semi-major-axis 200, semi-minor-axis 10, and semi-major-axis-angle 90 is a long, thin ellipse, 400 pixels wide, with the long axis vertical, centered at center. Now, with a start-angle of 0 and a length-angle of 90, all of the ellipse in the lower right quadrant is drawn and no part is drawn in any other quadrant.

center should be a position (see make-position). stream should be a cg-stream.

See also cg-drawing.html.


draw-ellipse-sector

Generic Function, cg package

Arguments: stream center semi-major-axis semi-minor-axis semi-major-axis-angle start-angle length-angle

Draws an ellipse sector on stream. An ellipse-sector is an ellipse-arc with the endpoints of the arc connected to the center of the ellipse, like a piece of an elliptical pie.

The ellipse is defined by the center (a position) and the two half-axes, lengths from the center to the farthest point on the edge and to the nearest point on the edge, called the semi-major-axis and the semi-minor-axis. (Technically, the major axis should be longer than the minor axis but the two arguments need not have that relationship.) Because the Windows ellipse drawer can only draw ellipses that are vertically or horizontally oriented, the semi-major-axis-angle argument must be a multiple of 90. Other values will signal an error. The argument specifies the angle between the semi-major-axis and a line parallel to the x-axis passing through the center.

Angles are measured in degrees clockwise from the 3 o'clock position. The endpoint coordinates may be determined by calling ellipse-start-and-end.

So, the ellipse created when specifying semi-major-axis 200, semi-minor-axis 10, and semi-major-axis-angle 90 is a long, thin ellipse, 400 pixels wide, with the long axis vertical, centered at center. Now, with a start-angle of 0 and a length-angle of 90, all of the ellipse in the lower right quadrant is drawn, along with the lines from the ends of the arc to the center and no part is drawn in any other quadrant.

center should be a position (see make-position). stream should be a cg-stream.

See also cg-drawing.html.


draw-focus

Generic Function, cg package

Arguments: widget

draw-focus returns whether a focus rectangle is drawn in a multi-picture-button, picture-button, static-picture, scrolling-static-text, or chart-or-plot. The value may be set at creation time by passing the draw-focus initarg, or any time later by calling (setf draw-focus).

The value may be true or nil. The default is t except for multi-picture-button, where it is nil.

Draw-focus for a multi-picture-button

If true, then when the widget has the keyboard focus it draws a focus rectangle around the particular button that has the focus within the widget. Pressing the spacebar will then press or unpress that button. The arrow keys will move the focus to other buttons, scrolling as needed, and clicking on a button will move the focus to that button.

If nil, then no focus rectangle is drawn, and pressing the spacebar will not press a button because no particular button has the keyboard focus. Clicking the mouse on buttons will still press and unpress them.

Draw-focus for a scrolling-static-text

When the draw-focus property of a scrolling-static-text is true and the widget has the keyboard focus, then a focus rectangle is drawn that overrides the rectangle that would be drawn by the border-color