Return to cmdcache.3l CVS log

Up to [Research Unix] / researchv10dc / 630 / man / src / p_man / man3

Annotation of researchv10dc/630/man/src/p_man/man3/cmdcache.3l, revision 1.1

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.