Introduction

First of: This uses IceUI but does not require IceUI. If you use this option definition, your widget will still work without IceUI and someone could even write a standalone widget to handle the options.

The idea is to have a simple way to define options in any widget without having to implement a GUI to change them (and without having to change the source code to change them).

Option types

These belong into a global table named options (see examples). It won't work with a local table and no other name is checked for options.

• bool
  Code:
    deployment = {
      name   = 'Deployment Mode',
      desc   = 'Players deploy a limited number of units before the game starts',
      type   = 'bool',
      value  = false,
    }
• number
  Code:
    NearIdle = {
      name   = 'Near Idle',
      desc   = 'This means that factories with only 8 build items left will be shown as idle.',
      type   = 'number',
      value  = 8,
      min    = 0,
      max    = 25,
      step   = 1
    }
• string: the input is kinda weird atm but should be better next Spring version (I hope)
  Code:
    string_opt = {
      name   = 'String Option',
      desc   = 'an unused string option',
      type   = 'string',
      value  = 'BiteMe',
      maxlen = 12,
    }
• color
  Code:
    BorderColor = {
      name   = 'Border Color',
      desc   = 'The color of the boxes surrounding an icon.',
      type   = 'color',
      value  = { 0.0, 1.0, 0.0, 0.65 },
      disabled = true
    }
• list: atm a list with 3 items will be "radioButtons", more than 3 will be a dropdown box
  Code:
    gamemode = {
      name   = 'Game Modes',
      desc   = 'Change the game mode',
      type   = 'list',
      items  = {
        {
          key  = 'normal',
          name = 'Normal',
          desc = 'Normal game mode',
        },
        {
          key  = 'deploy',
          name = 'Deployment',
          desc = 'Players deploy a limited number of units before the game starts',
        },
        {
          key  = 'tactics',
          name = 'Tactics',
          desc = 'Players select a limited number of units before the game starts (without any factories)',
        }
      },
      value  = 'normal'
    }
  or
  Code:
    list_test = {
      name   = 'List Test',
      desc   = 'List Test Option',
      type   = 'list',
      value  = 'opt1',
      items  = { 'opt1', 'opt2', 'opt3', 'opt4' }
    }

Changes to map/mod options

I tried to make it as close to the mod/map/ai options as possible but I did change a few things:

• The "key" component of the option is now the actual key of the table:
  
  Code:
  options = {
    {
      key    = 'deployment',
      name   = 'Deployment Mode',
      desc   = 'Players deploy a limited number of units before the game starts',
      type   = 'bool',
      def    = false,
    }
  }
  becomes
  
  Code:
  options = {
    deployment = {
      name   = 'Deployment Mode',
      desc   = 'Players deploy a limited number of units before the game starts',
      type   = 'bool',
      def    = false,
    }
  }
  The reason it was like that is to be able to have a userdefined order. The reason I changed it is because you can access them in your code easier:
  
  Code:
  if options.deployment.value then [...] end
• The "def" component becomes a "value" component because it does specify the default value in the source code but it actually contains the changed value from the widgets point of view. This leaves us at:
  
  Code:
  options = {
    deployment = {
      name   = 'Deployment Mode',
      desc   = 'Players deploy a limited number of units before the game starts',
      type   = 'bool',
      value  = false,
    }
  }
• I'm not sure if the map/mod options have a "disabled" component but I guess it doesn't make much sense for them. I added it for options depending on each other or whatever you want (see Interaction).
• I added a 'color' type which has a table of four floats (a color) as value.

That's pretty much what I changed. Everything else (all the different option types) should work with IceUI in the attached preview version (only useful for widget devs). If you think something should work and it doesn't, please tell me, since I probably forgot to test that specific case.

Interaction

The main feature of the interface is the fact that options.x.value gets updated automatically with the user-defined value.

You can however also define a function that gets called whenever an option is changed:
The cool thing is that you can change whatever you want in your options table (inside the OnChange functions but also everywhere else) and it takes immediate effect in the GUI. This allows to disable options based on the setting of others or add items to a list or other cool stuff.

To change anything, just assign new values (ie options.Test.disabled = true).

I'm not sure if everything is already changeable (haven't worked on this for three weeks now) but if something isn't, please post it here.

Try it yourself

First, download the latest version of IceUI and then add an options table to your widget as shown above. I attached to simple examples to get you going.

CustomModOptions.lua as another reference

Seems like when this is ready it should be made a part of spring, but I've been saying that about IceUI for a long time now.

I just updated the first post since I just commited the changes to the real IceUI..

I really think this (and that Lua Guide PDF thingy recently posted) should be stickied because IceUI or not a standardized way to define options for widgets can't hurt either way and this is as close to map/mod/ai options as I could get..

It would also be cool if someone could write a widget independent of IceUI that handles these options so even players who don't use IceUI can set them without changing the source code.. If anyone is interested in that please tell me since you can probably reuse a lot of my code..

stickied

hmm...
about the change of the key (change from map/mod/ai -> widgets):
as i dont know any LUA, i wonder if it would be possible to write a wrapper function, that would convert your options format to the map/mod/ai one. not that i know of anything where it would be needed right now, but as you said, it can't hurth anyway.
i am thinking of something like:


then we could use the same code like for other options for accessing the options from the engine or other places eg.

hope a better article

With some help from Meltrax, I have added the functionality for these widget settings to work in EPICMenu (CA's menu system that uses the ChiliGUI lua framework.). It's about 95% complete.

What this means is you can implement a widget with these settings and they would show up in both IceUI and EPICMenu. This would allow users to tweak your widget's settings in IceUI when playing BA and in EPICMenu when playing CA, for example.

Missing functionality from EPICMenu

• Settings controls won't update if something else updates them. For example if you have both IceUI and EPICMenu, and change a setting in IceUI, it won't reflect in EPICMenu (unless you reload the widget). This won't break anything, but it's on my todo list.
  
• Until Chili has support for dropdown menus, items you define as a list will just be a bunch of buttons.

Extra functionality in EPICMenu

• options_order table (optional). Use this to specify the order of your options since they use an unordered table. Example:
  
  
  Code:
  options_order = { 'NearIdle', 'deployment' },
  options = {
    deployment = {
        name   = 'Deployment Mode',
        desc   = 'Players deploy a limited number of units before the game starts',
        type   = 'bool',
        value  = false,
      },
    NearIdle = {
        name   = 'Near Idle',
        desc   = 'This means that factories with only 8 build items left will be shown as idle.',
        type   = 'number',
        value  = 8,
        min    = 0,
        max    = 25,
        step   = 1
      }
  }
  
  
  NearIdle will be first and deployment will be second.
  
• options_path string. Specify the path of the menu that your widget settings will show up in. Foregoing this will place the settings under Settings/Misc/<widget name>.
  
  Code:
  options = {
     ....
  }
  options_path = 'Settings/Interface/Chat'
  
  
  Also, each option can be given its own path to override the options_path setting.
  
  Code:
  options = {
     someoption = {
        name = 'Some Option',
        type = 'bool',
        value = 'false',
        path = 'Settings/View'
     },
     ....
  }
  options_path = 'Settings/Interface/Chat'
  
  
  
• Button control (button). Use it to performs an action with OnChange. It doesn't save any values to settings.
• Label control (label).
• Text window (text). Adds a button that creates a window containing your text, useful for help text.

Some of the above syntax may yet change depending on the future of how Meltrax and I work this out. But not in any drastic way.

There are several widgets in CA using these settings that you can use as examples. Here are a few:

• Chili Resource Boxes (under Interface)
• Chili Chat (under Interface)
• ChiliTip (under Interface)
• Stereo3D (under Effects)
• Complete Control Camera (under View)
• Chili Chat Bubbles (under Interface)