[1.2.0] Toolbar 1.7.13 - Common API for draggable/resizable buttons toolbar

[blizzy78]

Hi, there are quite a few plugins now that add various GUI buttons to the game. Right now, every plugin author has to implement button behaviour themselves. Also, there is no consistent button style between different plugins' buttons.

I have written a plugin that is targeted towards those plugins. Specifically, it provides an API for third-party plugins to provide GUI buttons to a toolbar. Those buttons then can invoke an arbitrary action specified by the plugin's author, such as opening a new window. The ultimate goal of this plugin is the separation of specifying a button's contents (such as text or image) and its action from the actual display style and position of the button. The player should be free to position buttons anywhere they please.

Please see this (older) video demonstrating some of the features:

 

 

Feature List

 

• A draggable and resizable toolbar holds all buttons
• Buttons have a texture (icon)
• Custom button order can be maintained
• Unlimited number of toolbars per game scene
• Custom button folders can be created to improve organization
• Toolbar position is saved between KSP restarts
• Toolbar will auto-clamp to screen area so that it cannot be dragged off-screen
• Toolbar may auto-hide itself if positioned at screen edge
• Clicking a button invokes an arbitrary action specified by plugin author
• Every button looks the same, no need for plugin author to provide any styles

 

Resources

Download Toolbar Plugin 1.7.13

Source code: https://github.com/blizzy78/ksp_toolbar

(The Toolbar Plugin is licensed under the BSD 2-clause license.)

Classes relevant to plugin authors:

 

• ToolbarManager (ToolbarManager.Instance field only)
• IToolbarManager (interface to the toolbar manager)
• IButton (interface to a button once created by the toolbar manager)
• IVisibility (fine-grained control over button visibility)
• GameScenesVisibility (button visibility controlled by current game scene)

 

Full example code: https://github.com/blizzy78/ksp_toolbar/blob/master/TestButtons/TestButtons.cs (This is placed into the public domain for obvious reasons.)

How to Integrate Into Your Plugin

There are two ways to add Toolbar Plugin support to your plugin:

Create a hard dependency on the Toolbar Plugin and bundle it with your download

 

1. Download the pre-compiled archive linked above.
2. Copy the folder GameData\000_Toolbar\ into your KSP installation that you use for development.
3. Make sure your project is targetting .NET 3.5.
4. Add a dependency on Toolbar.dll to your project.
5. Use the Toolbar Plugin's API (example code).
6. Heads-up: Make sure to call IButton.Destroy() when your plugin is unloaded. If you don't do this, your buttons will stay around while your plugin is long gone.
7. When publishing your plugin, be sure to include the folder 000_Toolbar\ in your download's GameData\ folder.
   • Do not modify anything in the 000_Toolbar\ folder. Do not rename this folder.

 

 

Use the Toolbar Plugin wrapper to provide optional Toolbar Plugin support

 

1. Download the pre-compiled archive linked above.
2. Copy the folder GameData\000_Toolbar\ into your KSP installation that you use for development.
3. Make sure your project is targetting .NET 3.5.
4. DO NOT add a dependency on Toolbar.dll to your project.
5. Copy the ToolbarWrapper.cs file into your project.
6. Edit the namespace in ToolbarWrapper.cs to match your plugin's namespace.
7. Use the Toolbar Plugin's API (example code).
   • You can use ToolbarManager.ToolbarAvailable to check if the Toolbar Plugin is actually available. Note that you must not call any other Toolbar Plugin API methods if this returns false.
   • Heads-up: Make sure to call IButton.Destroy() when your plugin is unloaded. If you don't do this, your buttons will stay around while your plugin is long gone.
   • When publishing your plugin, you can optionally include the folder 000_Toolbar\ in your download's GameData\ folder.
   • Do not modify anything in the 000_Toolbar\ folder. Do not rename this folder.

 

Change Log

Please see the addon release thread for a list of changes.

Edited October 15, 2016 by blizzy78

[ferram4]

Sure, I'd be up for using this; I've been thinking about rewriting FAR's GUI thingy anyway.

Would it be possible to have a version of this that would work in the SPH + VAB as well?

I gather the best way for us to interface with it would be to include the dll as a reference in the project and work from there, correct?

I assume that you'd plan for distribution to be handled like ModuleManager, where every plugin using it includes it in the GameData folder, with the most recent version available in your release thread, correct?

It looks good; count me in!

[blizzy78]

Would it be possible to have a version of this that would work in the SPH + VAB as well?

Yes. For now I have only concentrated on making things work. There is no support yet to control in which scenes your buttons are visible.

I gather the best way for us to interface with it would be to include the dll as a reference in the project and work from there, correct?

Yes.

I assume that you'd plan for distribution to be handled like ModuleManager, where every plugin using it includes it in the GameData folder, with the most recent version available in your release thread, correct?

That I haven't decided yet.

[XanderTek]

Great idea! I think it would be even better if it allowed for all the buttons to be grouped into a single toolbar so that they could all be moved/hidden together. I often find myself with a number of mod buttons on the screen, and rearranging them all individually can be a pain.

[diomedea]

At last someone who took the task for this absolutely needed plugin. Hope it will be a resounding success and set a standard for every mod.

If I may add some to your list of mods using buttons or tabs:

- VOID (VAB/SPH and Flight, button)

- ISA MapSat (Flight, button)

- SCANSAT (Flight, large button)

- Haystack (Flight, tab)

- Chatterer (Flight, button)

- MultipleSaves (Flight, rectangular button)

Please, allow the user to decide where to place the stack of buttons, to configure the relative position of each button/tab, to close or put the stack out of view.

[sirkut]

I would love to use it for the Infernal Robotics gui. That way one small icon could hide/show the UI.

[lincourtl]

Oh hells yes! Please!

[blizzy78]

I have updated the OP to include links to full source code (having inline documentation), links to classes relevant to plugin authors, and a link to a fully compiled test installation that you can simply drop into your KSP installation to test the plugin. You can also use that DLL to compile against it.

Please note that although all of that is available now, this plugin is not yet ready for distribution to players (aside from testing.) Please DO NOT include the DLL into your plugin's download.

[nothke]

Oh my god!! This is exactly the thing I suggested some time ago! I intended this to be my second plugin project =)

You don't need a list of mods to have this capability. EVERY MOD needs this cause almost every mod has a gui that needs to be hidden

(my thread suggestion was deleted I guess, I can't find the trace of it)

also could you make the standard gui style to be of KSP and not stock Unity one? It's better to have it match the rest of the HUD, it would also match the Kerbal map info buttons already existing in KSP

Edited November 30, 2013 by nothke

[blizzy78]

also could you make the standard gui style to be of KSP and not stock Unity one? It's better to have it match the rest of the HUD

Actually, I personally like the default Unity style more. But I don't see a problem to let the player decide which style they want.

[nothke]

I found just images of my suggestion, something I called "slotgird":

in the space center scene you could arrange the slotgrid:

Instead of this bringing interest into someone who knows how to write plugins to ACTUALLY make it, the thread turned into a discussion about "would modders use it or not, should you push this to devs to implement it or not, the modders won't even see it.. blah blah.."

Your version is better because it doesn't bind to the grid, but everyone can position where they want. I would also add different gui action capability so they change color such as "on active" "on warning".. and so on, but I guess modders can already do this no?

Edited November 30, 2013 by nothke

[blizzy78]

I would also add different gui action capability so they change color such as "on active" "on warning".. and so on, but I guess modders can already do this no?

At this time, a button's text, icon, and text color (if there is text) can be changed at any time. So this allows a plugin author to change button appearance.

[blizzy78]

I may have forgotten to tell everyone how to move buttons around, so here goes:

At the start of the plugin, every new button that hasn't been positioned by the player is auto-positioned on the screen. Also, every button is locked into position. To unlock a button, simply right-click it. You can then move it around freely. While unlocked, the button cannot be clicked in the regular way. To lock button position again, right-click a second time.

[TaranisElsu]

I had made a simpler version of this: https://github.com/taraniselsu/TacLib/blob/master/Source/Icon.cs, which has been available for others to use -- and a couple modders have asked to.

Yours looks good, but it is much more complex.

I like the idea of a toolbar like nothke's suggestion:

but I want it to function such that I can put a bunch of icons on it and then show/hide it with one click. And it collapses down to a single icon. That way my screen is not all cluttered with the icons everywhere but I still have easy access to them all.

I know that you are planning on it, but I wanted to reiterate that it is very important that you allow us to control in which scene(s) the icons show. My mods show things in Flight, the Space Center, or the VAB/SPH. Others' mods show in the Tracking Station.

P.S. I do not like the idea of only rearranging them in the Space Center scene. I would like to arrange them in the Flight scene, and the Space Center scene is getting enough icons of its own so I do not want the flight ones to show there also.

[blizzy78]

I know that you are planning on it, but I wanted to reiterate that it is very important that you allow us to control in which scene(s) the icons show. My mods show things in Flight, the Space Center, or the VAB/SPH. Others' mods show in the Tracking Station.

Every button has a Visible property to control whether it is currently visible or not. You could simply check which scene the game currently is in, then set the Visible property accordingly.

[Mihara]

Seeing as how you're apparently quite aware that your plugin needs to be loaded first before any other plugin that links to it can access it, here's a couple of thoughts:

1. I think the alphabetical order takes GameData directories into account as well, i.e. DirectoryA/aaa_plugin.dll will be there before DirectoryB/aaa_plugin.dll.
   
2. Names that start with 0 will be loaded even earlier than that, so you might as well put it in GameData\0_blizzy\0_Toolbar.dll.
   

[blizzy78]

I assume that you'd plan for distribution to be handled like ModuleManager, where every plugin using it includes it in the GameData folder, with the most recent version available in your release thread, correct?

A follow-up on this aspect: As I understood ModuleManager's code, every instance of it looks at all assemblies that have been loaded. If it finds one that is ModuleManager, and is a newer version, it would disable itself and leave the hard work to that newer version.

This approach works fine for ModuleManager, because it does all by itself. In the Toolbar Plugin, things are a little different: Third-party plugins would invoke a method to add new buttons, and register with an "on click" event handler for those buttons. I haven't tested anything yet, but I think the ModuleManager approach will be rather difficult here.

Of course, not all is lost. The simplest approach would be to not include the Toolbar Plugin DLL into third-party plugins' downloads, but to require the separate installation of the Toolbar Plugin by the player. Of course, that puts the burden on the player, which I see as a barrier to entry for third-party plugin authors here.

I think the alphabetical order takes GameData directories into account as well, i.e. DirectoryA/aaa_plugin.dll will be there before DirectoryB/aaa_plugin.dll.

Good point, I'll have to test that. Here's to hoping the plugin loader will ever be fixed.

[johnsonwax]

but I want it to function such that I can put a bunch of icons on it and then show/hide it with one click.

How about a setting for autohide? Just mouseover the area and it appears. Default to always show.

[SirJodelstein]

Very interested in this. Will definitely use this (whatever you come up with in the release) for the the Persistent Trails plugin.

[blizzy78]

Another followup on the issue of how to deal with the dependency on the Toolbar Plugin:

Without going into any of the complicated details here (many thanks to Majiir for tossing lots of ideas at me), I think I will be going for the following approach:

• Third-party plugin authors can grab a copy of the Toolbar.dll, reference that in their project as usual and compile against it.
  That of course will create a hard dependency on the plugin.
  
• In the third-party plugin's download, the Toolbar.dll must be included.
  This ensures that the hard dependency can be resolved, and there will be no need to have some sort of "fallback" because the DLL is always available.
  
• In the third-party plugin's download, the Toolbar.dll must be located under the path GameData\000_Toolbar\Toolbar.dll
  This serves two purposes:
  1) The path starting with "000_" ensures that the Toolbar.dll will be loaded as early as possible, so that dependent plugins will not fail to load.
  2) Using always the same path to install the Toolbar.dll in players' installations, this prevents all sorts of complicated problems when there is more than one copy of the DLL.

I will be working hard to ensure that the API will be upwards-compatible, so that a third-party plugin compiled against an older version of the Toolbar Plugin will work fine with a newer version of the plugin.

[Majiir]

It's worth noting that Mu has fixed the assembly loader for KSP 0.23 so alphanumeric ordering will no longer be needed for dependencies.

[blizzy78]

It's worth noting that Mu has fixed the assembly loader for KSP 0.23 so alphanumeric ordering will no longer be needed for dependencies.

Right, you were pointing that out to me on IRC. Depending on release dates, I should be changing the required path to remove "000_".

[Mihara]

Right, you were pointing that out to me on IRC. Depending on release dates, I should be changing the required path to remove "000_".

There's no harm keeping it even then, if you ask me, that makes it stand out and grab attention.

It's worth noting that Mu has fixed the assembly loader for KSP 0.23 so alphanumeric ordering will no longer be needed for dependencies.

Oh, and speaking of that. Will unresolved dependencies stop breaking the game as well?

Edited December 1, 2013 by Mihara

[blizzy78]

There's no harm keeping it even then, if you ask me, that makes it stand out and grab attention.

I'm not after attention, I just want this to work

[Mihara]

I'm not after attention, I just want this to work

Grabbing attention is important if you want it installed correctly, which will contribute to keeping it working.