|
Allegro CL version 11.0 | ||||||||
Generic Function, cg package
Arguments: widget
Returns the 3d border width of widget.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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:
font specifies the font that will be used for status-bar messages. The height of the status-bar is set to fit this font.
parts can be a list of section widths (a number or t) into which the status-bar will be divided. If some members of the list are t, then those sections will be assigned a width such that they are equally wide and just wide enough to make all of the sections cover the entire width of window.
min-height can be used to make the status-bar taller than its default, which is the height of the status-bar's font.
size-grip-p is designed to control whether a resizing icon is added at the right end of the status-bar (yes if true, no if nil) but the OS seems to add it in all cases.
along-top-p if true adds the status-bar to the top of window rather than the bottom as usual. The automatic resizing of sibling panes to make room for the status-bar is not implemented when the status-bar is placed along the top.
name, if supplied, should be a symbol (we recommend using a keyword) providing a programmatic handle for the status bar, suitable as the name argument to, e.g., find-named-object.
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.
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:
behind: if specified t, the new control will be placed behind the other sibling widgets in the occlusion stack. If nil (the default), the new control will be in front of the others and be first in the tab order. A value other than t or nil must be a sibling widget on dialog. The new widget will be placed behind that one in the occlusion stack.
When creating many widgets by calling add-component for each one, it may be more efficient to pass behind as t for each one, because the operating system creates child windows in back initially, and also there will be no movement of the keyboard focus to each new widget as it is created as there is when each one is added in front (if the parent window has already been expanded). (When creating the widgets instead by passing a list of the widgets as the :dialog-items initarg to make-window, they are added to the parent window in front-to-back order internally.)
hidden: If specified true, the new control will be added to the dialog but its window will not appear until the program later expands it explicitly. If nil (the default), the new control will appear with the dialog.
widget is returned.
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.
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 handlingGeneric 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.
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.
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.
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.)
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.
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.
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.
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:
window: the window to get the status bar.
status-bar: if passed, should be either a status-bar that was removed from a window, or a status-bar created with make-window with a call like (make-window 'status-bar ...)
number-of-lines: the number of lines of text that should fit into the status-bar's static-text widget. The status-bar dialog will be made of sufficient height to fit the requested number of lines. Defaults to status-bar-number-of-lines applied to window.
font: the font to use in the static-text widget of the status-bar dialog pane. The status-bar dialog will be made of sufficient height to fit this font. Defaults to status-bar-font applied to window.
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.
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:
menu: may be any menu, whether a menu-bar, pop-up-menu, or pull-down-menu.
menu-item: should be a menu-item.
position: may be either :start, :end, or a non-negative integer. :start adds the menu-item at the top of the menu. :end adds it at the bottom. An integer indicates an index into the list of menu-items, where zero indicates the top of the menu and any integer equal to or greater than the number of menu-items presently in the menu indicates the bottom.
after: may be either nil or a menu-item that is presently in the menu or the name of such a menu-item. If true and the menu-item is found in the menu, then the new menu-item is placed just below the after menu-item.
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.
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.
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.
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.
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.
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).
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.
Function, cg package
Arguments:
Returns a standard fixed-width font provided by the operating system. This is the suggested default fixed-width font.
Function, cg package
Arguments:
Returns a standard variable-width font provided by the operating system. This is the suggested default variable-width font.
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.
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.
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.
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.
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.
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.
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.
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:
prompt: should be a string. It will be displayed in the dialog.
button1: the value can be a symbol or a string naming the button, or a list whose first element is a symbol or string naming the button and whose second element is a help string. The button is labeled with the string or the print name of the symbol. If a help string is provided, it is displayed in the status bar when the cursor is over the button. If the user clicks on this button, the arguments value (a symbol, a string, or a list of a symbol or string and a string) is returned.
button2, button3, and button4: the value can be a symbol or a string naming the button, or a list whose first element is a symbol or string naming the button and whose second element is a help string, or nil. If the value is nil, the button is not displayed. The button is labeled with the string or the print name of the symbol. If a help string is provided, it is displayed in the status bar when the cursor is over the button. If the user clicks on this button, the arguments value (a symbol, a string, or a list of a symbol or string and a string) is returned.
title: this argument provides the title for the dialog. Its value should be a string. Note that all optional button arguments must be specified to supply a title (to preserve backward compatibility). Specify nil for a button that should not be displayed. If no title is specified, none is used.
stream: the owning window of the dialog; defaults to the stream returned by selected-window-or-screen. Note that all optional button arguments and the title must be specified to supply stream. Specify nil for a button that should not be displayed and for title if you want no title.
topmost: when this argument is true, the utility dialog invoked by this function will be topmost while it is present. A topmost window is one that remains on top of all other non-topmost windows, even those in other applications. This feature is particularly useful for modal dialogs that need to alert the user even if they have switched to another application. Note that all optional arguments must be specified to specify a value for topmost.
The position of the dialog when displayed is controlled by position-utility-dialog.
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:
stream: this keyword argument specifies the owner of the dialog. It defaults to the stream returned by selected-window-or-screen.
initial-value: specifies the value or values (if any) that should already be selected when the dialog appears, typically as a suggested default choice. The value may be either an element of choice-list or else nil to select no value. If allow-multiple is true, then the value may alternately be a list containing any subset of the choice-list elements. If the argument is not specified (as opposed to specifying nil), then the first choice in choice-list will be selected.
allow-multiple: if true, the first returned value is a list and the user may choose more than one value (with the shift or control keys in the typical Windows manner).
simple-click-toggle has an effect only if allow-multiple is true. In that case, if simple-click-toggle is true, then the user does not need to hold down the Control key while clicking in order to toggle individual choices. Note, however, that using this feature also disables the ability to choose a whole range of choices with a Shift-click. When this argument is nil (the default), Control-click toggles individual choices; Shift-click selects everything between the thing clicked on and a chosen item above, inclusive; and a click chooses an item and unchooses anything else selected, all of which is standard Windows behavior.
on-print: if specified, the value should be a function of one argument that returns a string. The strings resulting from applying the function to each element of the list will be used to print the elements of choice-list in the dialog. The value can be a function name or a function object. (See the similar on-print event handler for dialogs, whose value must be the name of a function of one argument that returns a string.) The default value is princ-to-string. Here is an example, where the choice-list contains integers and they are incremented by 1 before being displayed:
(ask-user-for-choice-from-list "X" (list 4 5 6)
:on-print
#'(lambda (x)
(format nil "~D" (+ 1 x))))on-change: the value may be either nil or a function or function name. If true, it is used as the on-change event handler for the item-list of the ask-user-for-choice-from-list dialog. The function will therefore be called as the user highlights each choice in the dialog. This may be handy for showing a help message for each choice. The function should take the three arguments widget, new-value, and old-value (as usual with an on-change handler), and should always return true (since returning nil would prevent the user from successfully selecting a choice). The default value of on-change is nil, which causes an internal on-change handler to be used.
topmost: when true, the utility dialog invoked by this function will be topmost while it is present. A topmost window is one that remains on top of all other non-topmost windows, even those in other applications. This feature is particularly useful for modal dialogs that need to alert the user even if they have switched to another application.
width and height: these arguments determine the width and height of the dialog displayed. The positioning of the dialog is determined, then, by position-utility-dialog. width and height should not be specified if dialog-exterior-box is specified, but use of dialog-exterior-box is deprecated in favor of width and height.
on-list-item-mouse-in: nil or a function that will be assigned as the on-list-item-mouse-in property of the dialog's item-list during this call, for arbitrary side effecs as the user moves the mouse cursor over individual items in the list. This parameter was added in release 11.0.
dialog-exterior-box: if specified, should be a box (see make-box). The dialog will be the size of the box but the location will be specified by position-utility-dialog (the top and left of the box are ignored). Again, use of this argument is deprecated in favor of the width and height arguments described just above. No value should be specified for this argument if values are specified for width and height (which override this argument).
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.
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.
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.
A universal time for the date that the user selected.
The year of that universal time.
The month (1 to 12) of that universal time.
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.
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:
prompt: an informational string explaining to the end user what they need to choose. The string appears in the body of the dialog. If unspecified or nil, the prompt "Select a folder." is used.
stream: the window or screen that will serve as the owner of the dialog while it is present. The dialog will be modal with respect to this owner window and all of its child windows and owned windows (that is, the user will not be able to access these windows while the dialog is present). Defaults to the stream returned by selected-window-or-screen.
root: This argument is no longer working for undetermined reasons. We recommend using the more versatile function ask-user-for-new-or-existing-directory instead, specifying the initial-directory argument, which is the equivalent of root for that function. When this argument is working, the value should be a pathname, path namestring, or nil, indicating the directory that will appear as the root node in the dialog's directory tree. Only this directory and its subdirectory descendents will be presented for selection by the end user. nil means to include all available file systems. The final slash is optional when either a pathname or namestring is passed.
dont-go-below-domain: if true, then network folders below the domain level, (as defined by MSDN), will be excluded from the tree of choices (though network folders above the actual directories may still be viewed). If nil, directories on both the local computer and networked computers are accessible.
browse-include-files: if true, the dialog will display regular files in addition to directories, and either a directory or other file may be chosen by the end user and returned.
include-edit-box: if true, then a text-entry widget will be included on the dialog. If the absolute (complete) path namestring of an existing folder (with or without the final backslash) is typed or pasted here, it will be used instead of the folder that's selected in the outline widget (if any).
new-dialog-style: if true, then Microsoft's "newer style" is used, where the dialog is resizable, is centered on the screen, and has a "Make new folder" button for creating a new directory. The new style also provides a right-click menu in the outline widget for doing things such as renaming a folder. These features used together allow the user to create and then rename a new folder, though more awkwardly than with ask-user-for-new-or-existing-directory.
See also ask-user-for-existing-pathname and ask-user-for-new-pathname, which ask the user for a file rather than a directory.
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:
initial-name: the filename shown initially for selection. It can be any relative filename with respect to the initial directory (the value of :host). If nil or " " (the empty string), the initial name will appear as the currently allowed type, such as "*.cl". The default is " ". A non-nil value may be either a namestring or a pathname object.
initial-directory: the initial directory from which to select the file or from which to change directory. If this value is unsupplied, the default depends on the value of the ide:context-sensitive-default-path configuration property, but in most cases the most recent value is used. The value of *default-pathname-defaults* is used initially.
stream: specifies the parent window for the dialog that pops up. Defaults to the stream returned by selected-window-or-screen.
allowed-types: specifies what types of files appear in the dialog's list of existing files. The value is a list where each member specifies one of the choices in the drop-down list of file type choices. Each list member is a cons of (1) the string to appear in the list of file type choices and (2) a string of the form "*.foo;*.bar;..." that indicates the file type(s) that it represents. The first choice is the one that is initially in effect. For example, the value (("Text Files" . "\*.txt")("Pixmap Files" . "\*.bmp;\*.jpg;\*.jpeg")) would initially display all files whose type is "txt", and also allow the user to select the second choice to instead display all files of the types "bmp", "jpg", and "jpeg". (Users can always type in some other file if desired.) The default value of this argument is (("All files" . "\*.\*")) to display all files.
multiple-p: a Boolean which, if true, allows the user to select more than one file; the list of selected pathname strings is returned. If nil, only one file may be selected and the returned value is a pathname string or nil, if the user cancels the dialog. The default is nil.
change-current-directory-p: a Boolean which, if true, changes the Microsoft Windows current directory to be the final selected directory when you exit or cancel the dialog. If nil, the current directory is left unchanged. Default is nil.
share-aware-p: a Boolean which controls whether a file that is currently opened by another application can be selected. If nil (the default), the file cannot be selected. If true, the file can be selected.
default-extension: the value should be either nil or a string that names a default pathname extension. This value is used only if the end user has selected an allowed type such as "All Files (.)" on the file selection dialog that does not specify a particular type, and they type in a filename with no extension. In that case, the pathname returned by this function will have default-extension as its pathname-type. An exception is that if default-extension is the null string, it will result in a pathname whose type is nil rather than the null string, just as if default-extension were nil.
buffer-size: an integer specifying the size of the buffer that's used to return the seleced pathnames. This is used only on the Windows platform. The default value is (file-selection-buffer-size (configuration *system*)) (see file-selection-buffer-size, configuration, and *system*. The default should always be sufficient when asking for new pathnames, where the filenames must be typed in.
title: a string to display in the title-bar of the dialog. This is used only in CG/JS mode, due to the native Windows file dialog not offering this. This parameter was added in release 11.0.
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.
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:
initial-font: if passed, should be a font object to be displayed initially in the dialog; if not passed, then no initial font is displayed.
fixed-width-only-p: if true, then the choices displayed in the dialog will be only those fonts where every character is the same width, such as :courier.
minimum-size: if passed, should be a positive integer denoting the minimum acceptable point size of the font; all sizes are still listed in the dialog, but a pop-up error dialog will prevent the user from returning an unacceptable size.
maximum-size: if passed, should be a positive integer denoting the maximum acceptable point size of the font.
initial-point-size: If passed, overrides the pixel-size of the font indicated in the initial-font. This parameter is supplied because the font dialog displays sizes in points, and it is difficult to automatically map a common graphics pixel size to the desired point size for display.
stream: the owning window of the font dialog. All owned windows of this window will be unavailable to the end user while the font dialog is being invoked. Defaults to the stream returned by selected-window-or-screen.
stream-for-font: The list of font choices displayed on the dialog will be the set of fonts available for this stream. If the selected font is to be used in a window, then the default value of (screen *system*) (see screen and *system*) should be appropriate. But if the selected font is to be used on a printer stream, then you may want to pass the printer stream as the value of this argument so that the list of choices will include fonts provided by the printer driver.
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.
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:
owner: either the screen or a window. Defaults to the stream returned by selected-window-or-screen. If a window, then the modal dialog will be owned by this window (and therefore will stay in front of it) and will be modal with respect to this window (meaning that interactive gestures are disabled in all other windows of the window hierarchy that has this window as its root).
type: a keyword indicating whether a new or existing directory (or either) is being requested. The value must be one of the following three symbols:
:either (the default), meaning the user may specify either a new or an existing directory.
:new, meaning only a new directory may be specified.
:existing, meaning only an existing directory may be specified.
For either :new or :either, a text control will always appear below the outline for entering a new subdirectory name. For :existing, this control will appear only if always-show-text-box is true.
always-show-text-box: if true, then the text-entry widget for specifying all or part of the path textually will be always be included on the dialog; if nil, then the text-entry widget will be included when the type argument is :new or :either, but not when it is :existing. The default value is true.
title: a string to display in the title-bar of the dialog. The default string depends on the type argument.
prompt: a string to display in the body of the dialog to instruct the user what to do. The height of the prompt area in the dialog will be adjusted automatically so that the prompt string fits.
position: either a position object (see make-position) indicating the screen position of the upper-left exterior corner of the dialog, or nil (the default) to use a default position. The default position is determined by center-modal-children and center-all-modal-dialogs-on-screen, as with the other built-in utility dialogs.
width: either a positive integer indicating the exterior pixel width of the dialog, or nil to use the width that was used most recently with the specified owner, including interactive resizing that the user may have done. Initially a moderate default width is used.
height: either a positive integer indicating the exterior pixel height of the dialog, or nil to use the height that was used most recently with the specified owner, including interactive resizing that the user may have done. Initially a moderate default height is used.
scope: a keyword indicating whether local disks or network shares (or both) are to be included in the outline. The value must one of the following symbols:
:all (the default), meaning both local disks and network shares are included.
:local, meaning only local disks are included.
:remote, meaning only network shares are included.
special-folders: a list of special directories to include as top-level items in the outline widget, alongside the usual top-level items for local and remote file systems. The value should be a list where each member is a list of at least two things: (1) one of the keyword values that can be passed to the function win:special-windows-directory, (2) a string to display for the folder in the dialog, and (3) an optional third boolean value that indicates whether the outline item for the folder should initially be open to reveal its child folders.
The default value is ((:personal #+mswindows "My Documents" #-mswindows "Home")), which will include a "My Documents" item on Windows and the home directory item on Linux. On Linux, :personal is currently the only indicator that will be used. On Windows, the indicator :personal should be used for the "My Documents" folder, because the :my-documents argument to win:special-windows-directory does not seem to work.
Here is an example value that includes some additional possibly useful values on the Windows platform:
:special-folders '((:personal #+mswindows "My Documents"
#-mswindows "Home"
t) ;; show child folders initially
(:recent "My Recent Documents")
(:app-data "Application Data")
(:desktop "Desktop")))create-if-new: this argument is used only if the user specifies a new subdirectory. In that case, if create-if-new is true (the default), then the specified subdirectory is created automatically before its pathname is returned, and otherwise it is not. In any case, the second returned value will be true if and only if a new subdirectory was specified. Multiple directories will be created automatically if the specified path ends with a chain a multiple subdirectories that do not yet exist.
show-initial-directory-children: this argument is used only when an initial-directory argument is specified. If nil (the default), then no children of the outline-item for the initial directory are visible when the dialog appears. If true, then that outline-item is opened to reveal any immediate subdirectories of the initial directory.
show-local-file-systems: if true, then the top-level item for local disks or file systems will initially be open to reveal the individual file systems; if nil, then it will not be. The default value is true.
initial-directory: either nil (the default) or a pathname or namestring indicating the directory to which the outline will initially be opened. The specified directory (if any) will also be initially selected. This option is useful for suggesting the area of the directory hierarchy in which the user may want to select a directory, and for making it easier for the user to browse to the probable desired directory. When this argument is nil, the outline is always opened to show only the local disks and/or the network shares, and the topmost outline-item will initially be selected.
If this argument is a namestring rather than a pathname, it does not matter whether the namestring contains a final slash. Also, if the specified directory does not exist, the outline will still initially be opened to any upper levels of the specified directory that do exist. It is also OK to pass in the full pathname of a file that is (or could be) in the desired directory; the pathname name and type will be ignored.
initial-subdirectory: either nil (the default) or a string to display initially in the text control where the user may enter a new subdirectory name. This argument is ignored if the type argument is :existing (in which case the text control for a new subdirectory will not appear at all). When nil, this control will be empty initially.
show-initial-directory-siblings: this argument is used only when an initial-directory argument is specified. If nil (the default), then each level of the outline that is opened in order to display the initial-directory will show only the single child item that leads to the specified initial-directory. If true, then all siblings of each opened item will also be shown initially. The advantages of each choice are that the first shows less clutter, while the second provides more initial context. The user can navigate to any directory in either case, and a "partially open" outline-item in the nil case will show a plus icon to indicate that it has more children in addition to the one that it's already showing.
look-ahead: if nil (the default), then whenever an outline-item is opened to show its subitems, the icons for each subitem will always initially indicate that the subitem may be opened to show further subitems, even if in fact there are no further subdirectories for some or all of the newly-displayed directories. If true, then whenever new subitems are shown, the dialog will "look ahead" to see if each of the newly displayed subdirectories has any further subdirectories, and will display appropriate icons for each item to inform the user whether there will be anything further to see if each displayed item is opened. The advantages of each choice are that the first is faster, while the second provides additional useful information to the user. This option may be particularly slow for network shares.
prompt-for-password-if-needed: if true (the default), then if the user attempts to open a network share but the user's default username and password are not correct for that share, than a dialog is shown to allow the user to enter a different username and password. If nil, then a simple beep indicates when the user may not open a network share.
focus-on-new-subdirectory: if this argument is true and a valid initial-directory argument was specified, then the keyboard focus will be initially in the text control for typing in a new subdirectory name. Otherwise the keyboard focus will be initially in the outline control of the dialog. The default for this argument is true if the type argument is :new, and is otherwise nil. This option may be useful if the application is asking the user for a new subdirectory when the probable parent directory is known (and passed as the initial-directory argument); in this case the user can typically type in the new subdirectory name immediately and return.
select-file: whether the user can select a file or a directory. nil means that the user can select a directory only. :single means that the user can select one file. :multiple means that the user can select one or more files in the same directory (in which case the returned value is a list of pathnames rather than a single pathname). This parameter was added in release 11.0.
When selecting a file, this dialog (which is written in Common Graphics) is an alternative to the standard dialog of the underlying windowing system that is shown by ask-user-for-existing-pathname and ask-user-for-new-pathname. In CG/JS mode, those functions always calls this one internally, due to the lack of a built-in dialog for selecting a file on the server machine.
allowed-types: a list of file type specifiers that works as in ask-user-for-new-pathname. This is used only when select-file is true. This parameter was added in release 11.0.
default-extension: nil or a file type string like "txt". This is used only when select-file is true and this extension is a string, in which case it will be added to the file path if a file name is typed without a file type. This parameter was added in release 11.0.
initial-name: nil or a file name string that will be displayed initially in the widget for entering a file name. This parameter was added in release 11.0.
close-subtrees-on-close: the close-subtrees-on-close property of the outline control will be set to the value of this argument for this call. The default is nil for each call.
search-network-globally: This argument is used only on the Windows platform. To find the networked machines to list, a true argument will search the network "globally", whereas nil (the default) will search only "in the current context". The default is nil. This argument is passed (as the value of the global keyword argument) to win:network-machines; see that function for more information. This argument applies to Microsoft Windows only.
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.
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:
initial-name: the filename shown initially for selection. It can be any relative filename with respect to the initial directory (the value of :host). If nil or "" (the empty string), the initial name will appear as the currently allowed type, such as "*.cl". The default is "". A non-nil value may be either a namestring or a pathname object.
initial-directory: the initial directory from which to select the file or from which to change directory. If this value is unsupplied, the default depends on the value of the ide:context-sensitive-default-path configuration property, but in most cases the most recent value is used. The value of *default-pathname-defaults* is used initially. In earlier releases, this argument was called host. host is still accepted in place of initial-directory. Do not specify both.
stream: specifies the parent window for the dialog that pops up. Defaults to the stream returned by selected-window-or-screen. See screen and *system*.
allowed-types: specifies what types of files appear in the dialog's list of existing files. The value is a list where each member specifies one of the choices in the drop-down list of file type choices. Each list member is a cons of (1) the string to appear in the list of file type choices and (2) a string of the form ".foo;.bar;..." that indicates the file type(s) that it represents. The first choice is the one that is initially in effect. For example, the value (("Text Files" . "\*.txt")("Pixmap Files" . "*.bmp;*.jpg;*.jpeg")) would initially display all files whose type is "txt", and also allow the user to select the second choice to instead display all files of the types "bmp", "jpg", and "jpeg". (Users can always type in some other file if desired.) The default value of this argument is (("All files" . "\*.\*")) to display all files.
change-current-directory-p: a Boolean which, if true, changes the Microsoft Windows current directory to be the final selected directory when the user selects a file. If nil, the current directory is left unchanged. Default is nil.
multiple-p: a Boolean which, if true, allows the user to name more than one file; the list of selected pathname strings is returned. If nil, only one file may be selected and the returned value is a pathname string or nil, if the user cancels the dialog. The default is nil.
It is not clear how useful this option is but we include it because the operating system allows it. Users have to type the filenames into a dialog. Multiple filenames must be enclosed in double quotes and be space delimited ("foo.cl" "c:\tmp\bar.fasl").
share-aware-p: a Boolean which controls whether a file that is currently opened by another application can be selected. If nil (the default), the file cannot be selected. If true, the file can be selected.
warn-if-exists-p: a Boolean which, if true, pops up a warning dialog if the user selects a file that already exists. If nil, returns the existing filename string without complaint. Default is t.
default-extension: the value should be either nil or a string that names a default pathname extension. This value is used only if the end user has selected an allowed type such as "All Files (.)" on the file selection dialog that does not specify a particular type, and they type in a filename with no extension. In that case, the pathname returned by this function will have default-extension as its pathname-type. An exception is that if default-extension is the null string, it will result in a pathname whose type is nil rather than the null string, just as if default-extension were nil.
buffer-size: an integer specifying the size of the buffer that's used to return the seleced pathnames. This is used only on the Windows platform. The default value is (file-selection-buffer-size (configuration *system*)) (see file-selection-buffer-size, configuration, and *system*). The default should always be sufficient when asking for new pathnames, where the filenames must be typed in.
title: a string to display in the title-bar of the dialog. This is used only in CG/JS mode, due to the native Windows file dialog not offering this. This parameter was added in release 11.0.
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.
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 names of the buttons (provided by the option1 and option2 arguments) do not have effect in themselves. Even though the button named "Cancel" is clicked, nothing is canceled. The string "Cancel" is returned as the third value and the program must interpret the returned value to act appropriately.
Pressing ENTER has the same effect as clicking on the button associated with option1. Pressing ESC has the same effect as clicking on the button associated with option2. Pressing the space bar is not equivalent to pressing ENTER (as it often is with dialogs) because the space is interpreted as a character in one of the strings.
Even if a string is unmodified by the user, a copy rather than the original argument is returned.
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.
(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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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).
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).
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).
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).
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.
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.
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 .
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.
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 .
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.
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 .
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 .
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.
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.
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.
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.
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).
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).
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.
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).
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.
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.
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.
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.
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.
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.
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.
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:
:frame: use a thick frame that includes a title-bar along the top. The title bar will include buttons for manipulating the window if options to make-window such as :minimize-button are true (as they are by default). Not applicable to widgets.
:dialog-box: similar to :frame, but without minimize and maximize buttons. Not applicable to widgets.
:palette: similar to :dialog-box, but with a shorter title bar that has a somewhat shorter font. The title bar also does not have a system menu button at the left. Typically used for "floating toolbar" windows. Not applicable to widgets.
:black: use a one-pixel-thick black border.
:none: use no border at all.
:none-allowing-title: use no border, but still allow the window to have a title-bar. Otherwise a borderless window will never have a title bar.
:plain: use a standard border and no title bar. This is the default value for various widgets that do not simply display a static value. Typically you do not need to specify the border for a widget, because the default is the appropriate value for that kind of widget.
:static: use a thinner border. This is the default value for various widgets that simply display a static value.
For group-box widgets the border can have the following special properties:
:2d: the border of the group-box is a plain gray line.
:raised: the body of the group-box is raised.
:raised-edge: the border is raised.
:sunken: the body of the group-box is sunken.
:sunken-edge: the border is sunken.
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).
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).
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.
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.
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.
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.
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.
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.
Generic Function, cg package
Arguments: box
Returns the coefficient of the bottom of box.
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:
:bottom: object maintains a constant distance between its lower edge and the lower edge of its parent window whenever that window is resized.
:scale: object maintains the same ratio of the distances from the top and bottom sides of its parent window whenever that window is resized. I.e., if the bottom edge was halfway between the top and bottom sides of the dialog before resizing, then it is still halfway between them after resizing.
:top: object maintains a constant distance between its lower edge and the upper edge of its parent window whenever that window is resized.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Function, cg package
Arguments: box
Returns the height of box.
See the description of the box class for general information on boxes.
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.
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.
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.
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.
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.
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.
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.
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*.)
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.
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.
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.
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.
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.
Function, cg package
Arguments: box
Returns the width of box.
See the description of the box class for general information on boxes.
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.
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.
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.
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.
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.
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.
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:
nil: the up-down-control is not connected to another control.
another-control-name (some editable-text-box): for any editable-text control with a companion up-down-control, the value of the buddy-widget property for that up-down-control is the name of that editable-text control.
buddy-widget is a property of the up-down-control class.
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.
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.
Function, cg package
Arguments: window
Moves window to the bottom of the occlusion stack, so that it will appear behind any overlapping sibling windows.
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:
nil: no borders with a three-dimensional appearance are drawn.
t: a thin border with a three-dimensional appearance is drawn around each button.
:when-pressed: a thin border with a three-dimensional appearance is drawn around each button whenever the button is in a pressed-down state or when the mouse cursor is over the button. At other times no border is drawn. This style also draws a separator bar between buttons wherever there is a :gap in the range (see the description of the range property in the description of multi-picture-button).
:thick: a thicker border is drawn around each button.
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.
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.
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.
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.
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.
Generic Function, cg package
Arguments: object
Returns true if the argument is an instance of the button-info class and returns nil otherwise.
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 |
UPWhere 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))Function, cg package
This function is no longer supported. typep instead.
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.
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.
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.
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.
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.
Generic Function, cg package
Arguments: pixmap
Stores pixmap internally so that it can later be retrieved by calling find-pixmap on its name.
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.
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.
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.
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.
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.
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.
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 importedThat 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 fileThen 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)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.
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.
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.
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.
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.
Generic Function, cg package
Arguments: window
Redirects all mouse events to window until released with release-mouse. See also with-mouse-captured.
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.
Function, cg package
Arguments:
Returns (and with setf sets) the current caret blink time. The units are milliseconds.
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.
Function, cg package
Arguments: window
Returns the current position for the caret of window. Use setf to programmatically move the caret.
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.
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.)
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.
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.
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.
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.
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.
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.
Generic Function, cg package
Arguments: row column
Returns true if the value in the cell can be dragged from the cell. Returns nil otherwise.
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.
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.
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.
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.
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.
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)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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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).
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.
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.
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.
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):
:button -- static-text-and-button-column-mixin
:check-box -- check-box-column-mixin
:combo-box -- combo-box-column-mixin
:editable-text -- editable-text-column-mixin
:static-text -- static-text-column-mixin
:lamp -- lamp-column-mixin
:pixmap -- pixmap-column-mixin
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.
For a static-text widget, return these values:
the symbol :static-text
the string to display in the cell, or else nil to defer to the read-cell-value method for the cell.
For a button widget, return these values:
the symbol :button
the name of the function to run when the user presses the button (see button-function)
a boolean value indicating whether the button should fill the cell (see button-fills-cell)
a string or pixmap to draw in the cell, or else nil to defer to the read-cell-value method for the cell
a background color for the button (see make-rgb) or else (more typically) nil to default to the cell-background-color method for the cell
a boolean value indicating whether the pixmap (if the fourth returned value is a pixmap) should stretch to fill the button, rather than being drawn at its canonical size
For a check-box widget, return these values:
the symbol :check-box
a string to display beside the check-box gadget (this value must be a string and not nil); the null string will center the gadget horizontally
a boolean value indicating whether the user must click on the check-box gadget itself, rather than anywhere in the cell, to toggle the value (see click-must-be-on-gadget).
For an editable-text widget, return these values:
the symbol :editable-text
a keyword indicating how type-in is initiated (see edit-start-trigger)
a keyword indicating how type-in is terminated (see edit-end-trigger).
For a combo-box widget, return these values:
the symbol :combo-box
a list of choices to display in the drop-down list (this is like the list that a range-reader function would return, but it must be a non-null list of choices)
a boolean value indicating whether the user may type in a new value, rather than selecting from the list of choices
a boolean value indicating whether to use a "real" combo-box for the list of choices rather than a pop-up-menu (see use-real-combo-box, though that option has been deprecated and so nil should always be returned here)
a boolean value indicating whether the user must click on the drop-down arrow gadget itself, rather than anywhere in the cell, to show the list of choices (see click-must-be-on-gadget)
a keyword indicating how type-in (if allowed) is initiated (see edit-start-trigger)
a keyword indicating how type-in (if allowed) is terminated (see edit-end-trigger).
For a lamp widget, return these values:
the symbol :lamp
a real lamp widget, created as usual with make-instance. Typically this widget will not also be used as a standalone lamp widget on a dialog, though it could be, and it may also be displayed by multiple grid cells, even in multiple grid-widgets.
For a pixmap, return these values:
the symbol :pixmap
an association list that maps application values to pixmap names, as with the pixmap-alist property of a grid-column
a boolean value indicating whether the pixmap should be stretched to fill the grid cell; see the stretching property
a boolean value indicating whether the user is allowed to interactively cycle through the cell's set of pixmaps; see user-modifiable
the name of a function to use for testing whether two application values are equivalent, as with the pixmap-value-test property; this value may be omitted to default it to widget-value-equal
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.
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.
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.)
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.)
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.
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.
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.
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 |
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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).
> (char-to-key-name #\*)
#\8
4 (4 is the value of shift-key)
> (char-to-key-name #\>)
vk-period
4If 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.
> (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.
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.
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.
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:
The window in which the key was pressed is a dialog-mixin instance or a child or other descendant of a dialog-mixin instance.
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.
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.
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 .
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.
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 .
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.
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 .
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.
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 .
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.
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:
:id - The ID of an object may be any sort of value, though the chart-object-id-equality-test function should be suitable for the values used. Typically it is a symbol. If nil or unspecified, an object's ID will default to the zero-based index of the object in the chart-objects sequence. This ID value will be passed to the chart-value-returner function of a chart-widget, or to the plot-value-returner function of a plot-widget, if one is used. An application can pass the ID to chart-value, set-chart-value, plot-value, or set-plot-value. Also, if no :label value is supplied here for an object, then the ID value is used to derive a label string to display for the object in the legend (typically modified by an on-print-chart-object function).
:label - This value can be a string to display for the object in the chart-legend of a chart or plot. If nil or unspecified, a label will be derived from the object's ID. Supplying this value for every object removes the need to write an on-print-chart-object function. If both are supplied, then an explicit label string will override the function.
:exclude - If a true value is specified for this key, then the object will currently not be drawn in the chart or plot. Also, if the range-bottom or range-top is automatically computed for a value-axis, then the object's data will not affect the determination of the range. This :exclude value will be toggled on or off automatically if the click-to-toggle-inclusion property of the chart-legend is true and the user clicks on the object's label in the legend.
:value-axis (chart-widget only) - This value should be either 1 or 2, though 1 is the default when nil or unspecified. A value of 1 means that a chart object will be associated with the primary value-axis of the chart-widget, which is drawn either on the left side or the bottom side of the chart (depending on the value of the chart-orientation property). A value of 2 will associate the object with the secondary value-axis, which is drawn either on the right side or the top side of the chart. A secondary value-axis is drawn only when one or more chart objects explicitly specify a value of 2 here in the chart-objects property. When two value axes are used, they can have different ranges, which is useful to compare two sets of values that are measured on different scales.
:x-axis (plot-widget only) - This works like :value-axis for a chart-widget, except that it applies to the value axes that always lie horizontally along the bottom or top of a plot-widget. 1 indicates the lower axis while 2 indicates the upper axis.
:y-axis (plot-widget only) - This works like :value-axis for a chart-widget, except that it applies to the value axes that always lie vertically along the left or right side of a plot-widget. 1 indicates the left axis while 2 indicates the right axis.
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 .
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.
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:
item-index is the zero-based index of the chart item to access, or nil to not specify an item index. Either this argument or item-id must be true. item-index takes precedence if both are true. The widget's chart-item-id-equality-test is used to find a matching item-index.
object-index is the zero-based index of the chart object to access, or nil to not specify an object index. The default is zero if neither this argument nor object-id is true. object-index takes precedence if both are true. The widget's chart-object-id-equality-test is used to find a matching object-index.
item-id is the arbitrary ID of the chart item to access, or nil to not specify an ID.
object-id is the arbitrary ID of the chart object to access, or nil to not specify an ID.
value-type is the type of to return. This argument may be one of the following keywords:
:value: the "main" value of a chart item and object pair.
:from-value: an optional starting value for a bar in a bar graph.
:high-value: an optional value that's normally greater than the main value.
:low-value: an optional value that's normally less than the main value.
:icon-size`: an optional size for a built-in icon drawn on a line graph.
See chart-widget and also .
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:
chart-widget is the chart being drawn.
value-type is the type of value that is being drawn. This will be one of the following keywords:
:id: the arbitrary ID to use for a chart item.
:value: the "main" value of a chart item and object pair.
:from-value: an optional starting value for a bar in a bar graph.
:high-value: an optional value that's normally greater than the main value.
:low-value: an optional value that's normally less than the main value.
:icon-size: an optional size for a built-in icon drawn on a line graph.
If value-type is :id, then the function should return an arbitrary value to use as the ID of the chart item, or else nil to default the ID to the item's zero-based index. This ID may then get passed to the item-axis' on-print-major-label or on-print-minor-label function to produce the string that is displayed on the item-axis tic mark for this chart item.
If value-type is anything other than :id, then either a number should be returned to display the specified type of value, or nil should be returned to not display that type of value.
(If a particular type of value will never be drawn, then for efficiency that value type could be removed from the value-types property of the chart-widget. That will prevent the chart-value-returner function from ever being called for that type of value.)
item-index is the zero-based index of the chart item being drawn. One exception is that when value-type is :id, the object-index and object-id arguments may be nil.
object-index is the zero-based index of the chart object being drawn.
object-id is the arbitrary ID of the chart object being drawn. This will be meaningful only if you have set up the chart-objects property of the chart-widget to specify object IDs; otherwise an object-id will default to the object-index.
See chart-widget and also .
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.
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))))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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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:
grid-widget: the grid-widget of which the grid-section is a part.
row-section and column-section: these define the intersection where the clearing is done.
drawing-pane: this is the child window on which drawing occurs. When clear-grid-section is called, the background-color of the drawing-stream is set to the background-color of the grid-widget.
section-box: this is the box in the drawing-pane's stream coordinates that covers the section that should be cleared.
See also draw-cell, draw-grid-section, draw-grid and grid-widget.
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.
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.
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.
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.
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.
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:
nil`: users can only deselect the button by clicking on another button in the same cluster (or by setting the value programmatically).
t: users can deselect the button by clicking on it again once it has been selected, i.e., the control will toggle on and off.
click-off is a property of the multi-picture-button, picture-button, and radio-button classes.
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.
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.
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*.
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.
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.
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.
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).
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"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.
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.
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.
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.)
Function, cg package
The symbol naming this operator has been moved to the dde package. Please see close-dde.
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.
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.
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.
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.
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).
Function, cg package
The symbol naming this operator has been moved to the dde package. Please see close-port.
Function, cg package
The symbol naming this operator has been moved to the dde package. Please see close-server.
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.
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.
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.
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.
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.
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 timescluster is a property of the picture-button, radio-button, and menu-item classes.
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.
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.
(setf (color-for-characters (configuration *system*))
(make-rgb :red 0 :green 120 :blue 160))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.
(setf (color-for-comments (configuration *system*))
(make-rgb :red 0 :green 120 :blue 160))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.
(setf (color-for-external-allegro-symbols (configuration *system*))
(make-rgb :red 0 :green 120 :blue 160))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.
(setf (color-for-external-cg-symbols (configuration *system*))
(make-rgb :red 0 :green 120 :blue 160))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.
(setf (color-for-external-cl-symbols (configuration *system*))
(make-rgb :red 0 :green 120 :blue 160))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.
(setf (color-for-global-variables (configuration *system*))
(make-rgb :red 0 :green 120 :blue 160))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.
(setf (color-for-strings (configuration *system*))
(make-rgb :red 0 :green 120 :blue 160))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.
(setf (color-for-user-functions (configuration *system*))
(make-rgb :red 0 :green 120 :blue 160))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.
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.
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.
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.
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.
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.
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.
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.
(setf (colorize-on-load-file (configuration *system*)) t)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.
(setf (colorize-on-typing (configuration *system*)) t)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.
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.
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.
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.
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.
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.
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).
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 |
(passing |
|
:previous-button |
(passing |
|
| :next-button |
(passing :next) |
|
| :last-button |
(passing :last) |
|
| :select-button |
|
|
| :search-button |
|
|
| :save-button |
|
|
| :revert-button |
|
|
| :new-button |
|
|
| :delete-button |
|
|
| :commit-button |
|
|
| :rollback-button |
|
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.
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.
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.
Generic Function, cg package
Arguments: window
Returns true if the argument is an instance of the common-status-bar class and returns nil otherwise.
Function, cg package
This function is no longer supported.
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.
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.
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.
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.
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:
pan - This must be enabled to enable any panning by dragging one or two fingers across the screen. Without the other panning options, two-fingered panning will be enabled both horizontally and vertically.
pan-with-single-finger-vertically - Enables panning vertically by dragging a single finger.
pan-with-single-finger-horizontally - Enables panning horizontally by dragging a single finger. This one appears to be disabled by default to allow the default behavior to select text instead.
pan-with-gutter - If enabled, restricts panning to either the horizontal or vertical direction, whichever one the gesture begins with, unless the user also moves in the other direction by some minimum amount that breaks out of the gutter.
pan-with-inertia - If enabled, calls to gesture-event will continue to be made for a brief period after a panning gesture ends during a drag, to allow the pan to gradually slow to a halt.
two-finger-tap - Enables a simple tap with two fingers.
zoom - Enables a two-finger pinch or spread gesture.
rotate - Enables a two-finger circular motion around a central point. This one appears to be disabled by default.
press-and-tap - Enables a gesture where one finger touches the screen momentarily, followed by a second finger while the first is still on the screen.
See also the touch-point class and About Touch Gesture Support in Common Graphics on Windows in cgide.html.
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.
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 changesGeneric 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.
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.)
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.)
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.)
(setf (console-title) "Console for Debugging")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.)
(setf (console-tray-icon) application-icon)See application-icon.
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.)
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.
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))))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))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.
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.
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.
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.
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.
Generic Function, cg package
The symbol naming this operator has been moved to the dde package. Please see 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-string.
Function, cg package
Arguments: box
Returns a copy of box. Boxes are created with make-box.
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.
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.
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.
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.
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.
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:
the stream that was passed in or created,
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.
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.
Function, cg package
Arguments: pos
Returns a copy of the argument position.
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.
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.
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.
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.
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.
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.
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.
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:
Killing a process (such as by calling process-kill) will always close all of the windows that were created by that process.
User keyboard and mouse events that occur on a window (and other messages that are programmatically sent to the window) will run code in the process that created the window.
When calling CG functions on this window later, the safest approach is to always do that in the creation process of the window. See post-funcall-in-cg-process for details.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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).
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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.
ocx-object-name-string should be a string naming the particular OCX control, such as "WebBrowser" or "MonthView". Refer to the documentation for the OLE application that was loaded, or its controls, to find these names.
doc-path: if doc-path is non-nil, then it should be a pathname or path namestring for a documentation file. Compiling (or simply macroexpanding) the def-cg-ocx-control form will generate the file with brief documentation for the control's properties, methods, and event-handler callback functions. The default is nil, in which case no documenation file is created.
use-native-size: if use-native-size is true, then the widgets of this class will ask the OLE server for the natural size for the widget, given its current properties, and the widget will be sized accordingly. If nil, then the widget may be made any size, as with other widgets. You should pass whichever value is appropriate for the control being defined; for example, true is appropriate for the MonthView control, which always draws a calendar at a standard size, whereas nil is appropriate for the WebBrowser control, which works at any size. The default value is nil.
toolbar-string-or-icon: if toolbar-string-or-icon is true, and the IDE is present, then a button for the new widget class will be added to the IDE's Components toolbar to allow you to place instances of the widget class onto form windows in projects. This argument is passed to ide:add-to-component-toolbar as its pixmap-or-title argument. The default value is nil.
toolbar-after, toolbar-tooltip, toolbar-help-string: if toolbar-string-or-icon is true (and the IDE is present), these values are passed as the values of the corresponding arguments (i.e. after, tooltip, and help-string) to ide:add-to-component-toolbar.
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.
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)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.
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.
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.
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.
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.
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.
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.
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).
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.
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.
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.
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).
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.
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.
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.
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")
nilGeneric 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.
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.
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:
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:
If the value of (default-height (configuration \*system\*)) is true, use that value for the height. (It is nil initially though.)
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.
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.
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))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*.
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.
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:
A symbol naming a function, or a function object. In this case, the function will be called, passing window-or-screen as the only argument. (When the shortcut-menu is invoked by pop-up-shortcut-menu, as usual, window-or-screen will be the window that was passed to pop-up-shortcut-menu).
A window. In this case, the window is selected by calling select-window.
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.
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.
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.)
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.)
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.
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.
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.
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.
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.
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.
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.
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*.
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.
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:
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:
If the value of (default-width (configuration *system*)) is true, use that value for the width. (It is nil initially though.)
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.
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.
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:
:reader: the name of a function for reading the property value. Defaults to the property name. (Always naming the property the same as the reader function is recommended.)
:writer: the name of a function for writing the property value. Defaults to the setf of the property name. (Using the setf of the reader function for the writer is recommended.) If a separate writer function is provided, it should be written to perform any side effects that are needed to keep the object and its environment in a consistent state.
Note on :reader and :writer: The name of the reader and writer functions for a property default to the name of the property and the setf of the name of the property respectively. But defining a property does not actually create the reader and writer functions for the property (regardless of whether the reader and writer names are specified explicitly), so the application must define these functions separately. Typically, a property is defined for a class and has the same name as a slot of the class, and the accessor methods that are created for the slot serve as the reader and writer of the property as well. Otherwise the reader and writer functions must be defined explicitly. See below for examples.
:type: a Lisp type that the property value must satisfy. The inspector will prevent invalid values from being used. Defaults to t, to allow any value.
:dependent-properties: a list of the names of other properties of the object whose values might be changed by the writer function as side effects. The Inspector uses this to redisplay related properties whenever the user changes a property value in the inspector. (In general, the Inspector does not know automatically to redisplay values that have changed once it has inspected an object, and the Refresh Values command on the Inspector's right-button shortcut menu may be used to ensure that the displayed values are current.)
:initarg: a keyword used by recreation-code to generate a lisp expression for recreating an object that has this property. Defaults to the keyword that has the same name as the property name symbol.
:help-string: a short documentation string for the property, or nil. Defaults to nil.
:editor-type: a value specifying which kind of extended editing will be used by the inspector for the property when the user clicks on the small button to the right of the value. Options are:
:long-expression: pops up a multi-line text editor. This is the default.
:multiple-choice: drops a list of choices.
:toggle: toggles between the choices when clicked. The default choices for :toggle are t and nil.
:color: pops up the color-selection dialog.
:font: pops up the font selection dialog.
:path: pops up the file selection dialog.
:menu: pops up the menu editor dialog.
:function: finds source code or generates skeleton code.
:choices: a list of possible values for use by the inspector when the editor-type is :multiple-choice or :toggle. Defaults to nil, unless the editor-type is :toggle, in which case the default is a list of t and nil.
:read-only: a flag to prevent modification of the property in the inspector. Defaults to nil.
:remake: a flag to indicate that the object that has this property should be recreated when this property is modified in order to completely effect the change. Defaults to nil.
:hidden: a flag to indicate that the inspector should not show this property. Useful when a property is inherited but is not useful on a particular subclass. Defaults to nil.
:repositioning (for controls): a flag to indicate that the control may be moved or resized when this property value is modified. Used internally to update handles on forms when needed. Defaults to nil.
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.
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:
:reader: the name of a function for reading the property value. Defaults to the property name. (Always naming the property the same as the reader function is recommended.)
:writer: the name of a function for writing the property value. Defaults to the setf of the property name. (Using the setf of the reader function for the writer is recommended.) If a separate writer function is provided, it should be written to perform any side effects that are needed to keep the object and its environment in a consistent state.
Note on :reader and :writer: the name of the reader and writer functions for a property default to the name of the property and the setf of the name of the property respectively. But defining a property does not actually create the reader and writer functions for the property (regardless of whether the reader and writer names are specified explicitly), so the application must define these functions separately. Typically, a property is defined for a class and has the same name as a slot of the class, and the accessor methods that are created for the slot serve as the reader and writer of the property as well. Otherwise the reader and writer functions must be defined explicitly. See the examples at the end of the defproperties entry.
:accessor: use instead of :read and :writer. Provides a reader and a setf method for the reader which works as a writer. Using the same name as the property is recommended. :type A lisp type that the property value must satisfy. The inspector will prevent invalid values from being used. Defaults to t, to allow any value. :dependent-properties A list of the names of other properties of the object whose values might be changed by the writer function as side effects. The Inspector uses this to redisplay related properties whenever the user changes a property value in the inspector. (In general, the Inspector does not know automatically to redisplay values that have changed once it has inspected an object, and the Refresh Values command on the Inspector's right-button shortcut menu may be used to ensure that the displayed values are current.)
:type: a type-specifier indicating the type of values that are allowed for this property. Any type-specifier may be used, such as the symbol integer or the list (and integer (satisfies evenp)), just as with the type-specifier argument to typep. This type is used only by the IDE inspector, which will reject a value that a user interactively enters for a property if the value is not of that type.
:dependent-properties: a list of the names of other properties whose values may change as a direct result of changing the value of this property. This list is used only by the IDE inspector, which will immediately update its display of any of these dependent properties that exist for an inspected object whenever the user interactively changes the value of this property.
:initarg: a keyword used by recreation-code to generate a lisp expression for recreating an object that has this property. Defaults to the keyword that has the same name as the property name symbol.
:help-string: a short documentation string for the property, or nil. Defaults to nil.
:editor-type: specifies which kind of extended editing will be used by the inspector for the property when the user clicks on the small button to the right of the value. The options are:
:long-expression: Pops up a multi-line text editor. This is the default.
:multiple-choice: Drops a list of choices.
:toggle: toggles between the choices when clicked. The default choices for :toggle are t and nil.
:color: Pops up the color-selection dialog.
:font: Pops up the font selection dialog.
:path: Pops up the file selection dialog.
:menu: Pops up the menu editor dialog.
:function: Finds source code or generates skeleton code.
:choices: a list of possible values for use by the inspector when the editor-type is :multiple-choice or :toggle. Defaults to nil, unless the editor-type is :toggle, in which case the default is a list of t and nil.
:read-only: a flag to prevent modification of the property in the inspector. Defaults to nil.
:remake: a flag to indicate that the object that has this property should be recreated when this property is modified in order to completely effect the change. Defaults to nil.
:hidden: a flag to indicate that the inspector should not show this property. Useful when a property is inherited but is not useful on a particular subclass. Defaults to nil.
:repositioning (for controls): a flag to indicate that the control may be moved or resized when this property value is modified. Used internally to update handles on forms when needed. Defaults to nil.
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.
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)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.
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)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.
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.
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.
value nil: Editable text is updated immediately after each keystroke.
value t: Editable text is updated when the keyboard focus moves from the control.
value nil: Editable text is updated immediately after each keystroke.
value t: Editable text is updated when the keyboard focus moves from the control.
up-down-control: when nil, the on-change functions of both the up-down-control and its buddy editable-text widget (if any) will be called each time the value increments as the user holds the mouse button down after clicking on the up-down-control.
When t: the on-change functions of both the up-down-control and its buddy editable-text widget (if any) will be called a single time when the mouse button is released, though the incrementing values will still be displayed in the buddy widget as the user holds the mouse button down.
value nil: Side effects are performed continously as the user drags the split-bar to a new location. (That is, once each time the system notices that the split-bar has moved by one or more pixels.) Side effects include moving and resizing any widgets in the widgets-to-move and widgets-to-resize properties, as well as calling the split-bar's on-change function if any.
value true: Side effects are performed only once at the end of drag.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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:
The icon is no longer the icon property of any window.
The icon is no longer the pixmap-icon property of any pixmap that may still get drawn.
The application will no longer draw the icon explicitly by calling draw-icon.
handle should be an integer that was returned by a call to either extract-icon-from-file or create-icon-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.
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.
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.
Macro, cg package
This function is no longer supported.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Generic Function, cg package
Arguments: x
Returns true if its argument is an instance of class dialog and returns nil otherwise.
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.
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).
:integrated-touch - an integrated touch digitizer is used for input.
:external-touch - an external touch digitizer is used for input.
:integrated-pen - an integrated pen digitizer is used for input.
:external-pen - an external pen digitizer is used for input.
:multi-input - an input digitizer with support for multiple inputs is used for input.
:ready - the input digitizer is ready for input. If this value is unset, it may mean that the tablet service is stopped, the digitizer is not supported, or digitizer drivers have not been installed.
See also the touch-point class and About Touch Gesture Support in Common Graphics on Windows in cgide.html.
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.
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.
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.
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.
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.
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.
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.
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.)
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:
:first: display the first instance in the internal sorted list.
:last: display the last.
:next: display the instance that is just after the current-instance in the sorted list, if any, and otherwise will do nothing.
:previous: like :next for the previous instance.
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))))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:
position: may be a position, or the special keyword :center, or nil. If non-nil, then the mouse cursor is moved to the indicated position before the mouse click is done. If window-or-widget-or-nil is non-nil, then the position is in that object's stream coordinates, and otherwise it is a screen position. The special :center value indicates the center of that object's client area. The default value is :center if window-or-widget-or-nil is non-nil, and nil otherwise.
Note that the mouse cursor is left at the specified position. If you would like to return the mouse cursor to where it was previously, then you should first call cursor-position or ncursor-position and save the current position, then call do-click, and finally call (setf cursor-position) to return the mouse cursor to its original position.
mouse-button: may be either :left, :middle, or :right to indicate which mouse button is to be clicked. The default is :left.
pre-expose: if this argument is true and window-or-widget-or-nil is non-nil, then that window or widget and all its ancestor windows are selected before the click is done, so that it is in front to receive the click. The default is t.
preview-seconds may be either a non-negative number indicating the number of seconds to sleep before pressing the mouse button, or nil to not sleep at all. The default is 0.5.
down-seconds may be either a non-negative number indicating the number of seconds to sleep after pressing the mouse button down but before releasing it, or nil to not sleep at all. The default is 0.5.
;; 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)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.
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.)
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:
preview-seconds: may be either a non-negative number indicating the number of seconds to sleep before pressing the key down, or nil to not sleep at all. The default is 0.5.
down-seconds may be either a non-negative number indicating the number of seconds to sleep after pressing the key down but before releasing it, or nil to not sleep at all. The default is 0.5.
shift, control, and alt: if shift is true, then the shift key is pressed before pressing and/or releasing the main key, and released after pressing and/or releasing the main key. control and alt work similarly for the Control and Alt keys.
down and up: If down argument is true, then the key is pressed down. If up is true, then the key is released. If both are true, the key is first pressed and then released. Both are true by default. It would not be useful to pass both as nil.
;; 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)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.
;; 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"))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.
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)))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.
There is a complete code example of using the double-buffered property for animation in the section Animation in cg-drawing.html.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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:
stream: the window or other graphical stream on which to draw the arrowhead. stream should be a cg-stream.
from-pos: a position object (see make-position) indicating the "other" end of a line that was drawn, so that the arrow will be drawn at the proper angle.
to-pos: a position object (see make-position) indicating the tip of the arrowhead.
length: the length of the arrowhead in streamq units (which are usually pixels). The default is 20.
width: the width of the arrowhead at its base in stream units. The default is 10.
fill: either nil, t, an RGB color object (see make-rgb), or an HLS color (see make-hls). This argument indicates how the arrow is to be filled.
If the value is nil (the default), the arrow is filled in the current background-color of the stream. This creates the effect of a hollow arrow (with the background color showing through the arrowhead), though in fact the interior is still filled in order to cover over the end of the actual line that was drawn beforehand.
If the value is t, then the arrow is filled with the current foreground-color of the stream, which is the color that is always used to draw the border of the arrowhead; this creates a solid arrow.
If the value is an RGB or HLS color object, then the arrowhead is filled with that color. This option may be used to fill the arrowhead with a different color than is used for the border of the arrowhead.
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.
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).
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 override