![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to cmdcache.3l CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Research Unix] / researchv10dc / 630 / man / src / p_man / man3|
Return to cmdcache.3l CVS log | Up to [Research Unix] / researchv10dc / 630 / man / src / p_man / man3 |
1.1 root 1: .TH CMDCACHE 3L
2: .XE "cmdcache()"
3: .SH NAME
4: cmdcache, useritems \- cache a command in the Application cache
5:
6: .SH SYNOPSIS
7: .ft B
8: #include <dmd.h>
9: .br
10: #include <menu.h>
11: .br
12: #include <object.h>
13: .PP
14: .ft B
15: Titem1 useritems;
16: .PP
17: .ft B
18: int cmdcache (s, m, b, u, e)
19: .br
20: char \(**s;
21: .br
22: Tmenu \(**m;
23: .br
24: Bitmap \(**b;
25: .br
26: void (\(**u)( );
27: .br
28: void (\(**e)( );
29:
30: .SH DESCRIPTION
31: The
32: .I cmdcache
33: function allows the caching of an application as a command to expand the
34: basic set of
35: global menu commands accessed from button 3, such as
36: \f3New\f1, \f3Reshape\f1, etc.. Although the basic set of commands mostly
37: deals with window operations, a cached command can have other functionalities. The
38: criteria to decide if an application should be cached as a command or
39: as an application is as follows:
40: .IP ""
41: The application runs without a window.
42: .IP ""
43: The application is compact and specialized, and its user
44: interface must be done through the mouse.
45: .IP ""
46: The scope of the application is global to the whole terminal.
47: .PP
48: An example of a cached command is the terminal resident \fBExit\fR command.
49: .PP
50: The application format is just a vehicle to download the code of the command into
51: the terminal; therefore, it should use a template
52: similar to the one used in the \fBEXAMPLE\fR
53: section, which has \fImain()\fR that calls the \fIcmdcache\fR function
54: with the right parameters and exits immediately.
55: .PP
56: The
57: .I cmdcache
58: function will use the null terminated ASCII string \fIs\fR as the
59: \fItag\fR name (see \fIcache(3L)\fR for a definition of a \fItag\fR name), and
60: also as the \fImenu\fR name of the command. The menu name will be displayed on
61: the \fBMore\fR menu for user selection. Note that a command can only be
62: accessed from the \fBMore\fR menu, and booting it through \fIdmdld\fR will not
63: work.
64: .PP
65: The bitmap \fIb\fR, if not null, will be displayed as an icon on the left on
66: the menu name of the command. It is recommended that cached commands have
67: an icon to differentiate them from cached applications, since the \fBMore\fR
68: menu lists all of them nondiscriminatively.
69: .PP
70: The cached command can have a submenu of its own if the argument \fIm\fR is
71: defined. The submenu \fIm\fR has to be generated \fIdynamically\fR, and the
72: menu generator must use the globally defined \fIuseritems\fR
73: (see \fItmenuhit(3R)\fR for details of a dynamic menu generation). The
74: structure for \fIuseritems\fR is \fBTitem1\fR,
75: which is used for all global commands and is defined as follows:
76: .PP
77: .RS 3
78: .nf
79: .ft CM
80: typedef struct Titem1 {
81: char *text;
82: struct {
83: unsigned short uval;
84: unsigned short grey;
85: } ufield;
86: struct Tmenu *next;
87: Bitmap *icon;
88: void (*dfn)();
89: } Titem1;
90: .fi
91: .RE
92: The field
93: \fInext\fR does not apply for items in a cached command's submenu (i.e.,
94: the terminal does not support fourth-level global submenus). Since submenu
95: off the item is not supported, the field \fIdfn\fR is also not relevant.
96: All other fields can be updated by the command's menu generator.
97: .PP
98: The argument function \fIu\fR is called by the terminal during the generation of the
99: dynamic \fBMore\fR menu. (The \fBMore\fR menu keeps changing because applications
100: and commands can constantly cache in and decache out.) When the terminal
101: processes a cached command, it copies the static information of the
102: command into \fIuseritems\fR: the argument \fIs\fR goes into the item field
103: \fItext\fR, the argument \fIb\fR into item field \fIicon\fR, the argument
104: \fIm\fR into item field \fInext\fR. Then the terminal will call the function
105: of type \fIvoid\fR
106: pointed by \fIu\fR, if present, with two arguments: The first one is a
107: pointer to the command object under consideration
108: (this argument is reserved) , and the other is a pointer
109: to the item structure being initialized (i.e., \fIuseritems\fR). The function
110: pointed by \fIu\fR may dynamically update the item's \fIufield.grey\fR, and
111: also re-initialize any fields of the item structure (e.g., if the current
112: conditions dictate that all items in the command's submenu are
113: invalid, the command may decide not to have a submenu, so the function
114: pointed by \fIu\fR may change the field \fInext\fR to null).
115: .IP \fBNote\fR
116: The fields \fIufield.uval\fR and \fIdfn\fR are used by the terminal for
117: housekeeping: they differentiate between selections of cached applications,
118: cached commands in the \fBMore\fR menu and items in third-level submenus of
119: those applications and commands. Even though it is possible to modify them,
120: it is \fIstrongly\fR not recommended unless the programmer understands
121: the terminal's internals.
122: .PP
123: If the argument \fIu\fR is not specified, the \fIcmdcache\fR supplies a default
124: function which initializes the \fIgrey\fR field of the item to null (no greying).
125: .PP
126: The argument function \fIe\fR of type \fIvoid\fR
127: is called when the command or an item from
128: its submenu \fIm\fR is selected. The function \fIe\fR accepts two arguments:
129: The first one is -1 if the command does not have a submenu, or
130: the index of the selected item (i.e., \fIuseritems.ufield.uval\fR)
131: if the command has a submenu.
132: The second argument is the pointer to the cached command object, but it
133: is reserved.
134: The function \fIe\fR is executed in the context of the
135: terminal's control process like other
136: global menu commands; therefore, some global
137: variables
138: relating to the downloaded application template and window parameters
139: such as \fIP\fR, \fIdisplay\fR, \fIDrect\fR, etc., do not have any meaning.
140: .PP
141: If the argument function \fIe\fR is not specified, no action is taken if the
142: item is selected. Also if the command has a submenu, selecting the command
143: menu name in the \fBMore\fR menu instead of an item in the command's submenu
144: will result to a null operation.
145:
146: .SS Return Value
147: If the command is successfully cached, the function \fIcmdcache\fR
148: returns a 1. Otherwise, a 0 is returned.
149: .PP
150: A failure may be due to the following reasons. Another command or
151: application
152: of the same name is already in the cache, or the terminal
153: runs out of memory when initiating the caching operation.
154:
155: .SH EXAMPLE
156: The following application caches a command
157: which lets the user pick a window and displays the name of the
158: application running in that window. The command supports
159: two options: the \fBfull\fR option displays the full name, and
160: the \fBclipped\fR option displays the full name clipped from
161: any path name prefix. The uargv field of the selected process
162: \f2p\f1 holds the \f2argv\f1 used by that process.
163: .PP
164: Note that if the chosen application is cached, the displayed
165: clipped name is the \fItag\fR name it is cached under.
166: .PP
167: .RS 3
168: .nf
169: .ft CM
170: .S -2
171: #include <dmd.h>
172: #include <menu.h>
173: #include <object.h>
174:
175: struct Tmenu obmenu;
176: Word qmarkdata[] = {
177: 0x3C00,
178: 0x7E00,
179: 0xE700,
180: 0xC300,
181: 0x0300,
182: 0x0700,
183: 0x0E00,
184: 0x1C00,
185: 0x1800,
186: 0x1800,
187: 0x0000,
188: 0x1800,
189: 0x1800
190: };
191: Bitmap qmark = {
192: (Word *)qmarkdata,
193: 1,
194: 0, 0, 8, 13,
195: 0
196: };
197:
198:
199: main ()
200: {
201: Titem1 *genesis(); /* command's submenu generator */
202: void showname(); /* command's executing code */
203:
204:
205: obmenu.item = (Titem *)0; /* dynamic submenu */
206: obmenu.generator = (Titem *(*)())genesis;
207: obmenu.menumap = TM_TEXT|TM_UFIELD|TM_NEXT|
208: TM_ICON|TM_DFN;
209:
210: cmdcache ("name", &obmenu, &qmark, 0l, showname);
211: }
212:
213:
214: Titem1 *
215: genesis (i, m)
216: int i;
217: Tmenu *m;
218: {
219: register Titem1 *item = &useritems;
220: /* MUST use "useritems" */
221:
222: switch (i) {
223: case 0: /* first item */
224: item->text = "full";
225: break;
226: case 1:
227: item->text = "clipped";
228: break;
229: default: /* last item */
230: item->text = (char *)0;
231: return (item);
232: }
233:
234: item->ufield.uval = i;
235:
236: /* WARNING: "useritems" is a global variable
237: ** used by all cached commands that have a
238: ** submenu, so we cannot assume that fields
239: ** that are not initialized by genesis() are
240: ** cleared since other
241: ** commands may initialize
242: ** them when they are running.
243: **
244: ** To be sure, just clear any unused fields.
245: */
246: item->ufield.grey = 0;
247: item->icon = (Bitmap *)0;
248: return (item); /* returns "useritems" */
249: }
250:
251:
252: void
253: showname (val)
254: int val;
255: {
256: register Proc *p;
257: register char *s;
258: Proc *point2window();
259: char *clipprefix();
260:
261: p = point2window (3); /* pick a window */
262: s = p->uargv[0]; /* "full" name */
263: if (val)
264: s = clipprefix(s); /* "clipped" name */
265: msgbox (s, (char *)0); /* display name */
266: }
267: .fi
268: .RE
269: .S +2
270:
271: .SH SEE ALSO
272: ucache(1),
273: cache(3L), decache(3L), tmenuhit(3R).
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.