[REL] Floating Framework v2.1 [73737]

Discussion in 'Released Mods' started by LavaSnake, October 30, 2014.

  1. LavaSnake

    LavaSnake Post Master General

    Messages:
    1,620
    Likes Received:
    691
    This mod provides an API that makes it easy for other UI mods to appear within a configurable floating frame that can be dragged to any position on the screen. The original version was written by @raevn and @wondible helped immensely with the panel magic needed for this update.

    As part of the update I've had to make some API changes so please check below if you're updating an old floating framework mod. Also, the settings option has been removed so you'll have to provide that yourself if you need it.

    What does it do?
    Floating framework allows mods to create dragable frames that act as a container for UI elements. They snap to the edges of the screen and remember their positions automatically. Basically, floating framework makes draggable UI elements easy. For an example of floating framework in action check out Commander HUD.

    Updates:
    • v1.0 - v1.2.1 - Old versions
    • v2.0 - API changes and compatibility with build 73737
    • v2.1 - Lock and unlock API calls added, see below
    How to use it:
    This mod is global so all of the API works in every scene, except for Live Game which has a couple of changes (see live_game notes section below).

    Create a frame
    Code:
    createFloatingFrame(id, width, height, options);
    • id - a unique ID for the frame.
    • width - the width of the frame
    • height - the height of the frame
    • options - a map containing additional options. Defaults shown in brackets are used if the particular option is not specified.
      • containment - selector string for containing element ("body")
      • snap - whether to snap to other frames (true)
      • rememberPosition - whether the frame remembers it's last position (true)
      • offset - where the top left of the frame will be positioned relative to. Defaults to top left. Can be one of:
        • topRight
        • bottomRight
        • bottomLeft
        • topCenter
        • bottomCenter
        • rightCenter
        • leftCenter
        • center
      • left - left offset from specified position
      • top - top offset from specified position
      • delayResize - adds a small delay (110ms) before the frame repositions after a screen resize. Needed on the start screen, as the container (starmap) only updates it's size 100ms after the window is resized (false).
    Note that if offsetting from a center, you'll typically want to have left/top equal to negative half width/height of the frame.

    Here's an example:
    Code:
    createFloatingFrame("commander_info_frame", 240, 50, {"offset": "topRight", "left": -240});
    Add content to a frame
    Code:
    $("#id_content").append("<p>Your Content Goes Here</p>");
    Note the "_content" suffix in the selector.

    Remove the saved position of a frame
    Code:
    forgetFramePosition(id);
    This will remove the position data for that frame from storage. The frame won't move but next time you call createFloatingFrame it will appear in the default position.

    Lock and unlock a frame
    You can disable and re-enable the floating ability using these calls:
    Code:
    lockFrame(id);
    Code:
    unlockFrame(id);
    The lock state of each frame is saved so if you lock a frame it will stay locked even after PA is restarted. You can check the state like this if needed:
    Code:
    localStorage["frames_id_lockStatus"]
    Special notes for live_game
    The live_game scene is a little different then most so I had to change the API up a little here. As you may or may not know the live_game scene is really a collection of panels. Each panel holds one of the tool bars (build bar, econ bar, and so on) and covers it's own small part of the screen. As a result there's no full-screen panel for floating framework to work in. To fix this floating framework adds a new panel called LiveGame_FloatZone which is full screen and takes care of all the messy details. For performance reasons I recommend that you minimize UI updates in floating frames since redrawing such a large area repeatedly can cause problems.

    First of all this means that no floating framework mods should run in live_game or any live_game panels. Instead use this code in your modinfo.json to run in LiveGame_FloatZone:
    Code:
    ...
    "scenes": {
       "LiveGame_FloatZone": [
          "coui://ui/mods/foldername/code.js"
       ]
    },
    ...
    Because LiveGame_FloatZone is a separate panel you can't access the live_game API directly. To fix that floating framework includes two useful little functions:
    Code:
    evalLiveGame("eval()", "reference");
    evalLiveGame will send the contents of the first string to live_game where it will be evaluated. The result will then be sent back and written to the local knockout observable reference.
    • eval - Must be a string that will properly output the data you want to get when it is run with the eval(""); function in the live_game panel.
    • reference - Must be a knockout observable in the global namespace of LiveGame_FloatZone. To get the result just subscribe to it or add it to your UI.
    Code:
    addLinkageLiveGame("okObject()", "reference");
    addLinkageLiveGame is exactly like evalLiveGame except it will update the reference on the fly as okObject gets changed. This only works if okObject is a knockout observable.
    • okObject - Must the name of a knockout observable in the live_game panel + "()". That way it will properly output the data you want to get when it is run with the eval(""); function and also be subscribable so updates can be sent.
    • reference - Must be a knockout observable in the global namespace of LiveGame_FloatZone. To get the result just subscribe to it or add it to your UI.
    Now I know this is a little confusing but it's actually the simplest way to do this and does all the hard parts for you. These examples should help clear things up.
    For evalLiveGame:
    Code:
    addLinkageLiveGame("afunction()", "model.anObservable");
    model.anObservable.subscribe(function(newValue) { console.log(newValue); });
    For addLinkageLiveGame:
    Code:
    addLinkageLiveGame("anObservable()", "model.anObservable");
    model.anObservable.subscribe(function(newValue) { console.log(newValue); });
    The mod Commander HUD uses all of this in a pretty simple way so if you want another example or a starting point to build your mod on I suggest downloading that.

    (If you want to know more about knockout observables or subscriptions click here.)

    How to get it
    Floating framework is a normal PAMM mod so you can make your mods require it by adding this to your modinfo.json:
    Code:
    ...
    "dependencies": [
        "com.pa.raevn.rfloatframe"
    ],
    ...
    If you have any questions or bugs please post them here and I'll try my best to help.
    Last edited: November 19, 2014
  2. DeathByDenim

    DeathByDenim Post Master General

    Messages:
    4,326
    Likes Received:
    2,118
    Nice! Off to fix my Notes mod!

    happy.png
    Raevn and LavaSnake like this.
  3. LavaSnake

    LavaSnake Post Master General

    Messages:
    1,620
    Likes Received:
    691
    Well tell me if anything goes boom. I'll be pleasantly surprised if I didn't miss a bug somewhere.
  4. DeathByDenim

    DeathByDenim Post Master General

    Messages:
    4,326
    Likes Received:
    2,118
    Ok, I found one thingy. You've put "global_mod_list" outside of "scenes". That means it breaks when you use it with raevn's fancy new pahub. That one only reads what inside "scenes".
  5. Raevn

    Raevn Moderator Alumni

    Messages:
    4,226
    Likes Received:
    4,323
    Don't worry too much about this, I do plan on supporting the legacy way of doing scenes also.
  6. DeathByDenim

    DeathByDenim Post Master General

    Messages:
    4,326
    Likes Received:
    2,118
    True, but it is still a legacy way of doing modding. :)
  7. LavaSnake

    LavaSnake Post Master General

    Messages:
    1,620
    Likes Received:
    691
    Thanks! I wasn't sure if it counted as a scene so I just used the old method since I knew it worked. I just uploaded the zip again with this changed so it should work if you uninstall it, delete the cache, and reinstall it. It's the same version number and stuff though since nothing really changed in the mod.
  8. LavaSnake

    LavaSnake Post Master General

    Messages:
    1,620
    Likes Received:
    691
    I just released version 2.1 which adds two new API calls for locking and unlock frames. Details in the API guide above!
    Fr33Lancer and proeleert like this.
  9. DeathByDenim

    DeathByDenim Post Master General

    Messages:
    4,326
    Likes Received:
    2,118
    @LavaSnake

    I think I found a "bug" in this framework. When you create a floating frame in the uberbar, it's not movable, nor can you interact with it in any way if it has a input text field for example. I've attached a sample mod that creates a floating frame from both start.js and uberbar.js. The one from start.js can be moved freely around the screen, but the one from uberbar.js cannot.

    That's a bug in the framework, right? I didn't see anything special in the uberbar.css that could cause this.

    Attached Files:

  10. LavaSnake

    LavaSnake Post Master General

    Messages:
    1,620
    Likes Received:
    691
    I'm guessing it has something to do with the sizing of the Uber bar but I'll try to look into it when I get some time. I've been really busy recently with other programming projects and school so it may be a little bit before I get to it.

    If you want to look into it yourself you can too. I don't have a problem with other people improving this. BTW, are you trying to use the uberbar for a mod or was this just a random find?
  11. DeathByDenim

    DeathByDenim Post Master General

    Messages:
    4,326
    Likes Received:
    2,118
    Yeah, no worries. I am looking into it too of course. :)
    I just wanted to let you know, since it may be easier for you to track down the issue.

    And yeah, I'm using it for the Notes mod. I'm putting the note icons next to all the player names in the Uberbar.
  12. LavaSnake

    LavaSnake Post Master General

    Messages:
    1,620
    Likes Received:
    691
    ok, try looking into the panel bounds and formatting. That gave me issues when I was writing the live game float panel so I think it might have something to do with it.
  13. proeleert

    proeleert Post Master General

    Messages:
    1,679
    Likes Received:
    1,653
    I fixed the Framework cause it was broken on new builds cause of changes with boot.js
    New version is on PAMM.
    cdrkf and ViolentMind like this.

Share This Page