1. This site uses cookies. By continuing to use this site, you are agreeing to our use of cookies. Learn More.
  2. We need your help nominating resources for or next YouTube video. Post here now.
    Dismiss Notice
  3. The winners of the 27th Texturing Contest have been announced. Congratulations to the winners!
    Dismiss Notice
  4. The Terraining Mini Contest Reload #2 - Machinery has began! Create a scene centered around a piece of machinery. Get creative tinker boys and girls!
    Dismiss Notice
  5. Join us on our next Custom Game Night, on Saturday, February the 24th at 7:00pm UTC! We'll see you all on our Discord and on Battle.net!
    Dismiss Notice
  6. The Cinematic Contest #7 - Time has began! Create a cinematic about Time!
    Dismiss Notice
  7. The Team Member Contest has ended! Check out Hive's created heroes and who could win the challenge here!
    Dismiss Notice

Integrating Tools Into JNGP

Discussion in 'Miscellaneous Tutorials' started by PurgeandFire, May 7, 2013.

  1. PurgeandFire

    PurgeandFire

    Code Moderator

    Joined:
    Nov 11, 2006
    Messages:
    7,224
    Resources:
    18
    Icons:
    1
    Spells:
    4
    Tutorials:
    9
    JASS:
    4
    Resources:
    18
    Integrating Tools Into JNGP

    Introduction:

    This quick guide will show you how to integrate a tool of your choice into JNGP, so that it may be executed from the toolbar. This tutorial covers:
    • Adding a menu.
    • Adding a menu entry.
    • Executing the tool.

    Many tools, such as GMSI, use this process for the convenience of the map maker.

    Note: The latest compilation of JNGP has a new feature, "Custom Menu Settings", that will automate much of this process. The below information is still useful, but you may want to consider checking that feature out. Here is the main thread:
    JassNewGen Pack

    Requirements:
    • JassNewGen Pack
    • NotePad, or any text editing document that can save as .lua.
    • A tool of your choice. I will be using BLP Lab as my example.

    *Note: Some of the screenshots will be from my Mac.

    Table of Contents:

    Initial Preparations:

    First, you must install the tool. Go to your JNGP folder.
    JNGP.png
    Place whatever tool you are using into your JNGP folder.
    BLP Lab.png
    Go to your JNGP folder. Open wehack.lua with a text editor. I recommend that you close JNGP Editor while you are modifying wehack.lua.
    wehacklua.png

    Adding a Menu:

    wehack.lua is executed on startup, adding the toolbars to WE and executing the appropriate applications/dlls. This is where we will add the toolbar menus. A toolbar menu refers to an individual "button" in the toolbar, such as "File", "Edit", "View", etc.

    The syntax to add a menu is relatively simple:
    Code (Lua):
    varName = wehack.addmenu("Menu Name")

    You will assign the menu to the variable represented by varName. We assign it to a variable because we will need to refer to it later when we add menu entries. The "Menu Name" is the name that will show up in the toolbar.

    In my case, I will add a toolbar menu titled "External Programs". You can write essentially anywhere in the file, but the order in which you write it will determine where it is on the toolbar. If you place the code all the way at the top, then it will be placed before "Extensions", "UMSWE", "Grimoire", etc.

    For that reason, I will place it at the end right before "isstartup = false":
    wehackmenu.png

    I named the variable "extPrograms", and the title shown will be "External Programs". This is how it will look in the editor:
    ExtPrograms.jpeg

    Adding a Menu Entry:

    If you open JNGP with your current wehack.lua, you'll notice that nothing happens when you click it (aside from highlighting the text). This is because it doesn't have any menu entries! This is the general format of adding a menu entry:
    Code (Lua):
    varName = MenuEntry:New( menu, "Menu Entry Title", callbackFunction )


    The menu entry will be assigned to the variable represented by "varName". The "menu" is the menu you want to place it under. Mine will be extPrograms, since that is what I named my variable. The "Menu Entry Title" will be whatever you want to name your menu entry. I will name mine, "BLP Lab".

    The final field is the callbackFunction. The function specified will be called when the menu entry is clicked. As such, we'll make a function to serve as the callback, right above the menu entry and such. This is how it will look like in the end:
    Code (Lua):
    function blpLabStartup()

    end

    extPrograms = wehack.addmenu("External Programs")
    blpLab = MenuEntry:New( extPrograms, "BLP Lab", blpLabStartup)


    Again, this is written in Lua. If you are not familiar with the syntax, please refer to:
    http://www.hiveworkshop.com/forums/jass-ai-scripts-tutorials-280/lua-object-generation-191740/#V

    After that code, this is what it will look like in the editor:
    BLPLab.png

    As an extra bonus, you can add what is known as a menu separator. This is just a line that separates one set of menu entries from the rest. Here is the syntax:
    Code (Lua):
    wehack.addmenuseparator(menu)

    So if I add the following code after the menu entry code:
    Code (Lua):
    wehack.addmenuseparator(extPrograms)

    This is what it will look like:
    BLPLabMenu.png

    Starting The Program:

    Now we just need to make the program run. The line is:
    Code (Lua):
    wehack.execprocess("path.exe")

    There are two other functions for this, wehack.runprocess and wehack.runprocess2. The first waits for exit code and reports error, the second just waits for exit code and doesn't report errors. execprocess doesn't wait for exit code. We only need to use wehack.execprocess.

    Now, all we need to do is place the line above into the function "callback" that we specified. The path is simply the path to the program. The paths are relative to the jassnewgenpack folder unless otherwise specified. This is why I placed the tool into the JNGP folder itself. In my case, the path will be:
    Code (Lua):
    wehack.execprocess("BLP Laboratory/blplab.exe")

    Note that you include spaces, and that you use a single forward slash "/" to navigate inside a directory (folder).

    If your program has no folder, then the path will be simply the name of the executable file. This is what our code will look like in the end:
    Code (Lua):
    function blpLabStartup()
        wehack.execprocess("BLP Laboratory/blplab.exe")
    end

    extPrograms = wehack.addmenu("External Programs")
    blpLab = MenuEntry:New( extPrograms, "BLP Lab", blpLabStartup)


    Now to test it. It should open the program:
    Works.png

    Lua

    You can also run Lua files through a menu entry. Instead of execprocess, just use:
    Code (Lua):
    dofile("path.lua")


    This will allow you to execute Lua through JNGP without copying and pasting the code. This will be very convenient if you have several maps that use the same Lua code.

    Why?

    • It is convenient.
    • It is cool.
    • More importantly, this tutorial will help those programs that are designed to be integrated into WE. If you have a tool that you think would be sensible to include in the JNGP package (the new ones by moyack), then just PM me.

    F.A.Q.

    • Q:
      Why doesn't it work?

      Lua is case sensitive. Make sure you have all your capitalizations in order. Also make sure you don't have any typos in the syntax. The code may run into an error, but it won't throw an error.
    • Q:
      Why doesn't it apply right away?

      wehack.lua is ran on JNGP WE's startup. In order for it to apply, you have to close and reopen WE. I suppose you could add a menu entry to run a lua file with such changes, but I haven't tested it.
    • Q:
      How do I make entries that can be checkmarked (toggled on or off)?

      The function format is:
      Code (Lua):
      varName = TogMenuEntry:New( menu, "Title", callback, default )
      -- default should be either true or false

      There are various functions to deal with them. For more information on the functions available, see the grimoire source:
      https://w3grimoire.svn.sourceforge.net/svnroot/w3grimoire/
      (old)


    Samples

    I'll continually post sample addons that may prove useful for modding.
    • View Output War3map.j - This will view the output war3map.j of the last saved map. When a vJASS script is saved, jasshelper will convert the code to vanilla JASS and place the contents under logs\outputwar3map.j. This option will allow you to start it up from the editor. Note that this only applies to the last map you saved (not necessarily the one you opened), and you may be prompted to associate the .j file with a certain program (choose notepad or some other text editor):
      Code (Lua):
      extPrograms = wehack.addmenu("External Programs")
      -- only add this if you do not have it already (it is the same menu from the tutorial)

      function viewOutputCode()
          -- updated for 1.5e
          if jh_isvexorian.checked then
              os.execute("logs\\outputwar3map.j")
          elseif jh_iscohadar.checked then
              os.execute("logs\\output_war3map.j")
          end

          -- os.execute("logs\\outputwar3map.j")
          -- ^ use this  function for pre-1.5e and comment out the rest
      end

      outputj = MenuEntry:New( extPrograms, "View war3map.j", viewOutputCode )

     
    Last edited: Sep 26, 2013
  2. Chaosy

    Chaosy

    Joined:
    Jun 9, 2011
    Messages:
    9,504
    Resources:
    13
    Spells:
    8
    Tutorials:
    5
    Resources:
    13
    useful, rep +
     
  3. sonofjay

    sonofjay

    Joined:
    Oct 28, 2011
    Messages:
    4,257
    Resources:
    20
    Packs:
    1
    Maps:
    13
    Template:
    5
    Tutorials:
    1
    Resources:
    20
    Sweet tutorial. I haven't tried it yet but this will surely be useful as I hate to put a lot of apps on my desktop.

    Thanks for sharing this info.

    EDIT:

    This does work on any tool right?
     
  4. Almia

    Almia

    Joined:
    Apr 24, 2012
    Messages:
    4,790
    Resources:
    35
    Spells:
    30
    Tutorials:
    4
    JASS:
    1
    Resources:
    35
    Cool :D
    Lemme mess with JNGP :D
    + rep

    edit
    Lemme add MDLVIS :D
     
  5. PurgeandFire

    PurgeandFire

    Code Moderator

    Joined:
    Nov 11, 2006
    Messages:
    7,224
    Resources:
    18
    Icons:
    1
    Spells:
    4
    Tutorials:
    9
    JASS:
    4
    Resources:
    18
    Yep, pretty much.

    It is almost like adding a shortcut inside JNGP's menu. As long as you spell the name/fields correctly it should work.

    Thanks for the comments. :)
     
  6. Faith

    Faith

    Joined:
    Dec 29, 2009
    Messages:
    886
    Resources:
    3
    Spells:
    1
    Tutorials:
    2
    Resources:
    3
    You sir, make an excellent tutorial!
    I'm going to try adding Button Manager. :p

    Very informative, but lacking in...

    AWESOME BBCODES


    EDIT: tried it out and it works. I'm gonna add a bunch of tools that I use to this thing.
    Are there any limitations to the tools? Ex. Quantity?
     
    Last edited: May 10, 2013
  7. Daffa the Mage

    Daffa the Mage

    Joined:
    Jan 30, 2013
    Messages:
    6,185
    Resources:
    14
    Maps:
    5
    Spells:
    8
    Tutorials:
    1
    Resources:
    14
    Useful tutorial, APPROVE this now!!
    +rep

    This is useful to messing with JNGP :)
     
  8. PurgeandFire

    PurgeandFire

    Code Moderator

    Joined:
    Nov 11, 2006
    Messages:
    7,224
    Resources:
    18
    Icons:
    1
    Spells:
    4
    Tutorials:
    9
    JASS:
    4
    Resources:
    18
    Thanks for the feedback everyone. :) I'll approve it since no one has reported any issues with it yet and the overall comments are positive.

    There aren't any practical limits. There may be a limit length-wise, but it isn't anything you'll hit very easily.
     
  9. Faith

    Faith

    Joined:
    Dec 29, 2009
    Messages:
    886
    Resources:
    3
    Spells:
    1
    Tutorials:
    2
    Resources:
    3
    Awesome, thank you!
    I look forward to adding EVERYTHING to this. c;
     
  10. Almia

    Almia

    Joined:
    Apr 24, 2012
    Messages:
    4,790
    Resources:
    35
    Spells:
    30
    Tutorials:
    4
    JASS:
    1
    Resources:
    35
    Question.
    Do MS-DOS work in this integration?
     
  11. PurgeandFire

    PurgeandFire

    Code Moderator

    Joined:
    Nov 11, 2006
    Messages:
    7,224
    Resources:
    18
    Icons:
    1
    Spells:
    4
    Tutorials:
    9
    JASS:
    4
    Resources:
    18
    No. MS DOS programs require special commands to run (they can't be executed natively afaik). You might be able to make a tool to execute it but it can't be ran through wehack.execprocess().

    Remember that this is essentially the same as right-clicking the program and selecting "Open"/"Run", but it adds a shortcut in the WE menu.
     
  12. Almia

    Almia

    Joined:
    Apr 24, 2012
    Messages:
    4,790
    Resources:
    35
    Spells:
    30
    Tutorials:
    4
    JASS:
    1
    Resources:
    35
    So, only .exe files do work? not MS-DOS, .txt, or anything that can be opened?
     
  13. PurgeandFire

    PurgeandFire

    Code Moderator

    Joined:
    Nov 11, 2006
    Messages:
    7,224
    Resources:
    18
    Icons:
    1
    Spells:
    4
    Tutorials:
    9
    JASS:
    4
    Resources:
    18
    You can.

    Code (vJASS):
    os.execute("path")


    For example:
    Code (vJASS):
    os.execute("war3.lua")


    Paths are still relative to the jassnewgenpack folder. There may be another way, but that is the function I would use. Note that it leaves the command prompt in the background, but it will disappear when you exit the program so it is a minor issue. There is probably a method to get rid of it, I am just too lazy to look it up.
     
  14. Almia

    Almia

    Joined:
    Apr 24, 2012
    Messages:
    4,790
    Resources:
    35
    Spells:
    30
    Tutorials:
    4
    JASS:
    1
    Resources:
    35
    Oh thanks :D
    I was going to add this feature on Debug I/O
     
  15. PurgeandFire

    PurgeandFire

    Code Moderator

    Joined:
    Nov 11, 2006
    Messages:
    7,224
    Resources:
    18
    Icons:
    1
    Spells:
    4
    Tutorials:
    9
    JASS:
    4
    Resources:
    18
    As for MS-DOS, did you mean a batch file? Yes, you can execute that. Here is an example for starting up the manual:
    Code (vJASS):
    wehack.execprocess("starter.bat ./grimext\\Grimexmanual.html")
     
  16. Almia

    Almia

    Joined:
    Apr 24, 2012
    Messages:
    4,790
    Resources:
    35
    Spells:
    30
    Tutorials:
    4
    JASS:
    1
    Resources:
    35
    MS-DOS == Batch File yes :D

    Thanks,i can update Debug I/O and add this :D
     
  17. Almia

    Almia

    Joined:
    Apr 24, 2012
    Messages:
    4,790
    Resources:
    35
    Spells:
    30
    Tutorials:
    4
    JASS:
    1
    Resources:
    35
    May i ask, Is the tool name execution case-sensitive? you know,will it run a simple name like "SomeTool.exe" even without the folder name?
     
  18. Adiktuz

    Adiktuz

    Joined:
    Oct 16, 2008
    Messages:
    9,697
    Resources:
    23
    Models:
    2
    Packs:
    1
    Maps:
    1
    Spells:
    16
    Tutorials:
    1
    JASS:
    2
    Resources:
    23
    wow... awesome... I never realized it was this easy to add things to JNGP...
     
  19. PurgeandFire

    PurgeandFire

    Code Moderator

    Joined:
    Nov 11, 2006
    Messages:
    7,224
    Resources:
    18
    Icons:
    1
    Spells:
    4
    Tutorials:
    9
    JASS:
    4
    Resources:
    18
    It is not case sensitive. So if you have:
    Code (Lua):
    dofile("Addons\\OutputWar3Map.lua")

    Versus:
    Code (Lua):
    dofile("Addons\\outputwar3map.lua")

    Both will work as long as the file exists (same for wehack.execprocess).
    *correction: on Windows

    However, you cannot choose it without the folder name. dofile will look for the file in the directory, but it won't search for it.

    I do have a sort of "Load Addon" thing that I've made (it works 100% but I haven't released it yet since I need to sort out a few details). Basically, instead of writing in the wehack.lua you can load a custom lua file and it will automatically load it every time JNGP opens. There is also a "Remove Addon" feature that will remove it from being loaded. That way, you won't make mistakes when you are adding a file because it will automate the process. This is all for lua files though. I think I may add one for exe files later on.

    But anyway, to solve your problem, you can just prompt them with a browser to search for the file:
    Code (Lua):
    function loadExeFunction()
        source = wehack.openfiledialog("Exe files (*.exe)|*.exe", "Select an exe to load ... ", true)
        -- prompt them with a dialog to choose a file
        -- limit it to exe files

        name = wehack.inputbox("Specify the exe name ... ", "Load Exe", "")
        -- prompt them to input the exe name for the menu

        if source ~= "" and name ~= "" then
            -- check to make sure the strings are not nil
            local callback = function() wehack.execprocess(source) end
            -- anonymous function for the callback
            MenuEntry:New(utils, name, callback)
            -- add the menu under "Extensions"
        else
            wehack.messagebox("Error: nil string", "Load Exe", true)
        end
    end

    loadExe = MenuEntry:New(utils, "Load exe", loadExeFunction)
    -- add the menu to load exes
     


    I didn't test it, it is just pseudo code so there might be errors. That is something along the lines of what you would do. However, the problem is that you must load it every time. That's why I made the "load addon" thing to write all the info to a lua file. I still have a few things to sort out though... such as if someone wants to reference a different lua file (requirements) or something like that.
     
    Last edited: Sep 26, 2013
  20. moyackx

    moyackx

    Joined:
    Feb 15, 2006
    Messages:
    761
    Resources:
    7
    Maps:
    4
    Spells:
    2
    Tutorials:
    1
    Resources:
    7