• Immutable Page
  • Info
  • Attachments

The former Beryl/Compiz Options Parser, known as BCOP, was moved into core and the CMake buildsystem in the 0.9.x series, 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 the options autogenerators

How it works

BCOP parses your metadata file and automatically generates option code for you. The actual option code is stored in plugin_options.cpp 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

  • Use the CMake buildsystem for plugins

Importing the Options class

BCOP will create a class of PluginnameOptions, which you import into your PluginScreen class. Thus you access all BCOP autogenerated code from within your PluginScreen class.

How things are named

BCOP names functions for retrieving options like so:

option_name becomes option_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

optionGetFooBar () or PluginnameScreen::get (screen)->optionGetFooBar ()

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

optionGetOptionName (), 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:

optionGetOptionNameOption (), 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.

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

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

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

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

  • optionGetColorOptionNameAlpha () 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 CompOption::Vector. CompOption::Vector's are a simple STL vector array of CompOption's

CompOptionValue's are made out of

union _CompOption::Value {
    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 optionSetActionNameInitiate () to do so. actionCallback must be set out as:

bool
PluginScreen::actionCallback (CompAction         *action,
                              CompAction::State  state,
                              CompOption::Vector options)
{
}

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)

Note that both the initiate and terminate setters take a boost::function<CompAction *, CompAction::State, CompOption::Vector>. This does not qualify for the object of the class "this". This means that your callback must be declared static. In order to avoid this, you can create a boost::function object by using boost::bind to specify the object for the class address. For example:

optionSetActionNameInitiate (boost::bind (&PluginnameScreen::actionCallback, this, _1, _2, _3));

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: optionSetOptionNameNotify(pluginOptionChangeNotifyCallback)

The callback must be constructed as:

void
PluginnameScreen::optionChanged (CompOption                 *opt,
                                 PluginnameOptions::Options num)
{
}

The same rule with the static prototype applies to this callback. If you want to have access to the object, you must use boost::bind to use the object.

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

Writing the metadata file

In order to have autogenerated options code, you will need to have the "useBcop = 'true'" in the <plugin> tag.

Display options versus screen options

Unlike previous versions, you must only use the <options> tag rather than specifying a display or screen context.

Development/zero-nine/BCOP (last edited 2010-07-25 09:27:38 by 124-169-107-122)