• Immutable Page
  • Info
  • Attachments

The Beryl/Compiz Options Parser, known as BCOP, is a tool to autogenerate code for working with options in Compiz plugins. It allows the developer to describe a plugin's options using XML code, which is then used by BCOP to generate a gconf schema, as well as the necessary C code to be included by the plugin. The advantage of this is that the developer only needs to maintain this one XML file.

How to use BCOP

How it works

BCOP parses your metadata file and automatically generates option code for you. The actual option code is stored in plugin_options.c and to use BCOP functions, you can retrieve them from including "plugin_options.h". BCOP code is automatically generated if you:

  • Specify <plugin name="plugin_name" useBcop=True> in your plugin.xml.in file

  • Specify your plugin name as PLUGIN=plugin in the plugin.info file

  • Use the Universal Makefile

How things are named

BCOP names functions for retrieving options like so:

option_name becomes pluginName_OptionName

where _ is replaced by Get or Set depending on what you are doing.

For example, a if you wanted to get the value of an option from a plugin named foo and an option named foo_bar then you would use

fooGetFooBar ()

Where is a CompScreen * or a CompDisplay * depending on the option's class (see below)

Accessing your options directly with BCOP

BCOP does all the hard work for you when it comes to accessing options. There are 5 important things to note when accessing options.

Accessing Value Options

Accessing value options could not easier. Again, accessing a value option is as simple as

pluginNameGetOptionName (), which returns the value of the option specified in OptionName. Remember that the return type is the same as what was specified in the XML file.

Accessing the option itself

If you want to access the option itself, for example, you need to write to the option, use:

pluginNameGetOptionNameOption (), which will return a CompOption * for the option you specified.

Accessing a Color

Accessing a Color is similar to accessing a normal option, except that it has five different functions to return five different shorts.

  • pluginGetColorOptionName () will return an unsigned short * which contains the Hex value for the colour itself

  • pluginGetColorOptionNameRed () will return an unsigned short * which contains the red value for the color

  • pluginGetColorOptionNameBlue () will return an unsigned short * which contains the blue value for the color

  • pluginGetColorOptionNameGreen () will return an unsigned short * which contains the green value for the color

  • pluginGetColorOptionNameAlpha () will return an unsigned short * which contains the alpha value for the color.

The latter four are useful only if you need to use a function which requires three different colors such as glColor4usv()

Accessing a List

Accessing a list will return a CompOListValue *. CompListValue's are made of:

typedef struct {
    CompOptionType  type;
    CompOptionValue *value;
    int             nValue;
} CompListValue;

CompOptionValue's are made out of

union _CompOptionValue {
    Bool           b;
    int            i;
    float          f;
    char           *s;
    unsigned short c[4];
    CompAction     action;
    CompMatch      match;
    CompListValue  list;

Setting a Callback for an action

Use pluginNameSetActionNameInitiate(CompDisplay *, actionCallback) to do so. actionCallback must be set out as:

static Bool
actionCallback (CompDisplay     *d,
                CompAction      *action,
                CompActionState state,
                CompOption      *option,
                int             nOption)

If you want to trigger a callback on a Terminate action - when the key or button is released, then you can use pluginNameSetActionNameTerminate (CompDisplay *, actionCallback)

Knowing when an option has changed

If you want to keep your option in a variable in a struct, for a 'continous state', your plugin can be notified on a particular option change. Setting an option change callback: pluginNameSetOptionNameNotify(CompDisplay * / CompScreen *, pluginOptionChangeNotifyCallback)

The callback must be constructed as:

static void
pluginDisplayOptionChanged (CompDisplay        *d,
                          CompOption         *opt,
                          PluginDisplayOptions num)

For display options and

static void
pluginScreenOptionChanged (CompScreen        *s,
                          CompOption         *opt,
                          PluginDisplayOptions num)

for screen options.

Typically, you would switch (num) and use the values in the enum PluginDisplayOptions to determine which options were changed.

Writing the metadata file

Display options versus screen options

The tags <display> and <screen> enclose <option>s which are specific to the display or to the screen, respectively. (See Development/Multihead for more information on the distinction between these two.) These options can also be inside <group>s and/or <subgroup>s.

There can only be one instance each of <display> and <screen> within the XML file. Therefore, if you have a mixture of display options and screen options within one group, the proper way to write the file is not to have a <group> containing <display> and <screen>; rather, you can create the same (identically named) <group> within both <display> and <screen>. They will appear as one merged group when displayed in CCSM.

Development/BCOP (last edited 2008-04-19 09:12:48 by CPE-58-161-138-188)