blizzy78

[1.0.5] Toolbar 1.7.10 - Common API for draggable/resizable buttons toolbar

382 posts in this topic

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.10

btn_donate_LG.gif

flattr-badge-large.png

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

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

Classes relevant to plugin authors:

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

The plugin makes a check against http://blizzy.de/toolbar/version.txt to see if a new version is available. No information is sent.


1.7.10, 2015-11-10
- Updated for KSP 1.0.5.
- Disabled KSP compatibility check for the time being.

1.7.9, 2015-05-02
- Updated for KSP 1.0.2.

1.7.8, 2014-12-22
- Updated for KSP 0.90.0.

1.7.7, 2014-10-09
- Fixed a bug in the KSP compatibility check.

1.7.6, 2014-07-26
- In addition to the automatic update check, the plugin now also gets KSP versions
from the update check server. In case the currently running KSP version is one of
those versions, the plugin will not complain about being incompatible with this
KSP version. This saves both players' and plugin authors' time.
- Updated for KSP 0.24.2.

1.7.5, 2014-07-25
- Updated for KSP 0.24.1.

1.7.4, 2014-07-17
- Updated for KSP 0.24.0.

1.7.3, 2014-06-26
- Improved positioning of folders and "drawables." This also fixes a bug that
occurred if a folder/drawable was blocking both the nav ball and the altimeter
at the same time.

1.7.2, 2014-06-22
- Folders and "drawables" (which are provided by third-party plugins) are now
prevented from blocking the nav ball and altimeter.
- Folders and "drawables" will now open in the same spot as they opened the
last time (as long as they fit on screen.) This should be helpful for third-
party plugin developers that provide "drawables" that may change their size
while being displayed.

1.7.1, 2014-04-02
- Updated for KSP 0.23.5.

1.7.0, 2014-03-03
- Fixed a bug that could prevent the saving of settings in certain situations.
- Plugin authors: Added new API to allow to display "drawables." These are any
GUI widgets that you wish to display that are tied to a particular button.
For example, drawables can be used to display a popup menu (see the
PopupMenuDrawable class and the example source code), or an informational
small window when hovering over a button. Drawables will always be positioned
near the parent toolbar (much like button folders.)
This new API is available for users of the official Toolbar wrapper as well.

1.6.1, 2014-02-28
- You can now choose different icons for folder buttons.

1.6.0, 2014-02-15
- Added support for multiple toolbars. You can add new toolbars by selecting
"Create New Toolbar" from the triangle drop-down menu. Each toolbar has its
own separate set of settings, folders, and visible buttons.
- The map view during flight is now considered a separate game scene. This
means that it is now possible to configure different toolbars for the
regular flight scene and the flight map scene.

1.5.3, 2014-02-13
- Fixed a bug where buttons marked as "important" could prevent the toolbar
from auto-hiding itself, even though those buttons have not been configured
to be visible.

1.5.2, 2014-02-08
- Removed the popup dialog that notifies about new buttons that became
available. Instead, the toolbar will always show the configuration button as
long as no other buttons are configured to be visible.
- Fixed a bug where the toolbar would lose the configured visibility of some
buttons.
- Fixed a bug where a newly-created folder would not respect the "show border"
setting of the main toolbar.
- Plugin authors: Added an official Toolbar Plugin wrapper that can be used to
provide Toolbar Plugin support without creating a hard dependency. Check the
development forum thread at http://bit.ly/1b1ZXda for details.

1.5.1, 2014-02-07
- Fixed a bug where the new buttons notification would pop up more often
than intended.
- Fixed a bug where folders would not display their contents.
- The update notification button can now be dismissed (hidden) by right-
clicking it.

1.5.0, 2014-02-07
- You can now configure the visibility of each button. For example, you can
now hide a button if you don't need it. Button visibility is saved in
relation to game scene.
Note: This change will cause a one-time reset of the toolbar, such that
no buttons are visible at first. Toolbar location will be preserved.

1.4.5, 2014-02-04
- Fixed another bug where the toolbar would get completely invisible under
certain circumstances.
- Various other minor improvements and bug fixes.

1.4.4, 2014-01-27
- Fixed a bug where the toolbar would get completely invisible under certain
circumstances.

1.4.3, 2014-01-25
- Various minor improvements and bug fixes.

1.4.2, 2014-01-13
- The plugin will now display a confirmation dialog before deleting a folder.
- The plugin will now check for incorrect installations and display a
warning if necessary.

1.4.1, 2014-01-05
- Fixed a bug that could sometimes cause buttons to render with Unity's
default skin instead of the KSP skin.

1.4.0, 2014-01-01
- You can now add custom folders to the toolbar, which can hold any number
of regular buttons for improved organization.

1.3.0, 2013-12-26
- You can now reorder the buttons on the toolbar. Button order is saved in
relation to game scene (for example, you can have a different button order
in the flight scene and the tracking station scene.)
- Plugin authors: Added new property IButton.EffectivelyVisible. See the
documentation of that property for details.

1.2.2, 2013-12-23
- You may now chose to use the KSP skin for buttons instead of Unity's
default 'Smoke' skin.
- The toolbar border can now be hidden.
- Improved the positioning/sizing of the toolbar after startup with respect
to the size that has been chosen previously by the player.

1.2.1, 2013-12-20
- Increased the size of the triangle button that opens the toolbar-specific
drop-down menu.
- Fixed a bug that could make the toolbar completely invisible under
certain circumstances.
- The toolbar should now no longer be visible during loading screens.
- Plugin authors: Added new events IButton.OnMouseEnter/OnMouseLeave.
See the documentation of those events for details.

1.2.0, 2013-12-17
- Toolbar position and size are stored in relation to the current scene now.
For example, you can place it at different positions in the vehicle assembly
building, the spaceplane hangar, and the actual flight scene.
- Plugin authors: There is a new property IButton.Important now. See the
documentation of that property for details.

1.1.0, 2013-12-08
- Added a new toolbar-specific drop-down menu where players can configure
the toolbar.
- Repositioning and resizing the toolbar should now be considerably easier.
- Added the ability to auto-hide the toolbar when it is positioned at the
screen edge.
- Plugin authors: No API changes were made in this version.

1.0.0, 2013-12-06
- Initial public release.

Edited by blizzy78
5 people like this

Share this post


Link to post
Share on other sites

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!

Share this post


Link to post
Share on other sites
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.

Share this post


Link to post
Share on other sites

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.

Share this post


Link to post
Share on other sites

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.

Share this post


Link to post
Share on other sites

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

Share this post


Link to post
Share on other sites

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.

Share this post


Link to post
Share on other sites

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 by nothke

Share this post


Link to post
Share on other sites
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.

Share this post


Link to post
Share on other sites

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

P5jOmDa.png

in the space center scene you could arrange the slotgrid:

mQINJ3u.png

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 by nothke

Share this post


Link to post
Share on other sites
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.

Share this post


Link to post
Share on other sites

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.

Share this post


Link to post
Share on other sites

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:

P5jOmDa.png

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.

Share this post


Link to post
Share on other sites
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.

Share this post


Link to post
Share on other sites

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. :)

Share this post


Link to post
Share on other sites
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.

Share this post


Link to post
Share on other sites

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.

Share this post


Link to post
Share on other sites

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

Share this post


Link to post
Share on other sites

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.

Share this post


Link to post
Share on other sites

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.

Share this post


Link to post
Share on other sites
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_".

Share this post


Link to post
Share on other sites
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 by Mihara

Share this post


Link to post
Share on other sites
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 ;)

Share this post


Link to post
Share on other sites
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. :)

Share this post


Link to post
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!


Register a new account

Sign in

Already have an account? Sign in here.


Sign In Now