How do I install a custom toolbar in the Epic editor 5.4?

[ggrosso0321]

Hi Everyone,

I built a custom toolbar by editing the editwindow.xml file in Arbortext (C:\Program Files (x86)\PTC\Arbortext Editor\lib\dialogs) however, I understand that it is not the correct way to add a custom toolbar. I've read a great part of the customization guide and also the programmers guide, but I just cannot find the information I need, in the form of a code sample,  that will help me do this all correctly.

I have removed the toolbar XML code from the editwindow.xml file and put it into a new file called "my-custom-toolbar.xml". I have also created a new file called "my-custom-toolbar.acl" that hopefully can be used to load the toolbar when a document is opened up in the Arbortext editor. Both of these files are in a following location on my PC:

C:\Program Files (x86)\PTC\Arbortext Editor\custom\editinit

I think I am close to succeeding because when I put a response("HELLO") message within the above ACL file, it showed up as expected. Unfortunately, my custom toolbar didn't show up, and worse, I don't know why.

Here is some information:

• The window_load_component_file(win, "my-custom-toolbar.xml") command returns 0 - I assume that return value means it failed as it does in C.
• I have two files, one ACL and one XML that are both in the above editinit directory.
• Below is the code found in the my-custom-toolbar.acl file that is suppose to load and display my custom toolbar in the Editor.

#BEGINNING OF CODE SAMPLE [Not part of the file]

function \
init(win = current_window())
{
  if (window_state(win) < 0) {
    response("Invalid window $win")     
    return
  }
 
  local doc = window_doc(win) 
  if (!doc_valid(doc)) {
    response("Invalid document")   
    return
  }  

  #===> Load my custom toolbar on Windows.
  window_load_component_file(win, "my-custom-toolbar.xml") 
  return win
}

# Calls the above function
init()

#END OF CODE SAMPLE [Not part of the file]

Could someone please lend me a hand and have a look and please tell me where I went wrong? Thank you in advance for your help and input everyone.

- George

[ClayHelberg]

Hi Giorgio--

I guess the first thing I would check is that your XUI file is correct. Try opening the XUI XML file in Editor. From there you should be able to do a completeness check to see if any required content is missing. For a XUI document to be loaded using window_load_component_file(), it must be a complete XUI document, i.e. have a top-level <window> element. Also remember that it needs the appropriate doctype declaration so Arbortext knows it's a XUI document.

If that checks out, you can test the XUI dialog by opening the XUI document in Editor and selecting Tools->View Dialog from the menus. This should show the XUI dialog, and allow you to edit it and see the changes reflected in the dialog view in real time.

Hopefully this will help you troubleshoot your toolbar. You are on the right path, I think, it's just a matter of figuring out what is preventing your toolbar from displaying.

--Clay

[ggrosso0321]

Hi Clay,

Thank you for your suggestions, they were very helpful. I loaded the xml file into the editor and the toolbar DID show up. I guess my problem actually is that it is NOT showing up when I open a specific type of document. In my case that's a docbook (actually docbook 4.5) document for editing. How do I get the toolbar to show in either of these two situations:

• When the editor is first started and nothing is loaded into it
• When I open a docbook document for editing.

Either one of these above cases would be good for me, but the first case (where the toolbar displays when I first start the editor) would be the most useful case for me.

I've attached a screenshot of the toolbar so you can see that it just sits in the UI with the other toolbars.

Thanks in advance,

- Giorgio

[ClayHelberg]

Hi Giorgio--

In that case, your script might be having trouble finding the XUI file. Your code only uses the filename, with no path info. You might need to be explicit with the location. The get_custom_dir() function can be helpful for this. Try modifying your editinit code along these lines:

#===> Load my custom toolbar on Windows.
  window_load_component_file(win, get_custom_dir() . "/editinit/my-custom-toolbar.xml")
  return win

Hopefully that will get it to find your toolbar. (FWIW, the return code of window_load_component_file() is just the opposite of what you thought; 0 means it was not able to load the document, 1 means success.)

Also, just as a tip, it is conventional to put XUI files into custom/dialogs, to keep it encapsulated from code in editinit or other custom dirs. If you move the XUI, of course you'll need to make the corresponding change in the code above.

--Clay

[ggrosso0321]

Hi Clay,

I put the two files (my-custom-toolbar.acl and my-custom-toolbar.xml) in the custom/dialogs folder as you suggested. The new code snippet now looks like this:

#===> Load my custom toolbar on Windows.
  window_load_component_file(win, get_custom_dir() . /

    "/dialogs/my-custom-toolbar.xml")
  return win

Unfortunately, the code does not seem to be firing at all. I tried putting a response("Hello") to see for sure and got nothing when the Arbortext editor first started. Obviously, I need to add some code that somehow calls the code within the my-custom-toolbar.acl file. Where should the code to call my init() function within the my-custom-toolbar.acl file be put?

- Giorgio

[ClayHelberg]

Only the XUI file itself goes in the custom/dialogs folder. The ACL code needs to stay in editinit in order to run automatically. So you should have custom/dialogs/my-custom-toolbar.xml and custom/editinit/my-custom-toolbar.acl. Try that and you should be in better shape.

[ggrosso0321]

Hi Clay,

I am not sure what I've done wrong here. I put the XML file in the custom/dialogs folder and the ACL file in the custom/editinit folder but the toolbar still does not display when I start the Arbortext Editor without any file loaded in it. When I have a file loaded in it, the toolbar displays twice; one on top of the other.

- Giorgio

[ClayHelberg]

I'm not sure why you're getting duplicates. The only thing I can think of is that you are not using a named package, so it's possible your init() function is overriding some other default init() function. A couple of things you can try:

Add a package declaration at the top of your ACL file. This acts like a namespace, and will prevent confusion with any other function called init(). Simply add a line like this at the top of your file:

package my-custom-toolbar;

Hopefully that will take care of the duplicate toolbar.

If you want the toolbar to load before you open any document, that can be a little trickier. You would need to move the code to custom/init, but you would also need to modify it so that it waits until the window is created before trying to load the toolbar. You would probably need to use a window callback or some other mechanism to do this. See window_add_callback() for information on how to do this.

--Clay

[ggrosso0321]

Thanks again Clay, that's gives me something to try out. I will report back my results as soon as I can.

- Giorgio

[ggrosso0321]

Hi Clay,

I tried adding the package as you suggested, but it displays an error "[A11315] Unrecognized modifier: -custom-toolbar" when it first opens. It turns out that it doesn't like the '-' characters in the package name. Here's the contents of the ACL file again.

###########################

#    my-custom-toolbar.acl file

###########################

package mycustomtoolbar;

function \
init(win = current_window())
{

  # This should stop the code if the

  # window is not created
  if (window_state(win) < 0) {
    response("Invalid window $win")     
    return
  }
 
  local doc = window_doc(win)
  if (!doc_valid(doc)) {
      response("Invalid document")   
      return
  }  

  #Load my custom toolbar on Windows.
  window_load_component_file(win, get_custom_dir() . "/dialogs/my-custom-toolbar.xml")

   return win
}

# Call the above function
init()

As you can see I added the package declaration. Now the code runs and I see my code reporting "Invalid window: -1"

- Giorgio

[ClayHelberg]

Sorry, it looks like it doesn't like the dashes in the package name. Try replacing with underscores:

package my_custom_toolbar;

[ggrosso0321]

As I mentioned in an edit, you were correct, it didn't like the '-' in the package name. It also didn't like the '/' operator for some reason. So I've kept the code on one line to avoid using that '/' character.

Now it runs through the code and reports "Invalid window: -1", which is from my ACL code. However, it doesn't show the toolbar when all is said and done. Or when I load a new document into the editor.

-Giorgio

[ggrosso0321]

Hi Clay,

I read the documentation on the window_add_callback (window, cbtype, callback) function but I still am not clear on how to actually use it. I tried the following code adjustments, please let me know if I am close and where I was mistaken.

BTW, my toolbar's ID is "myCustomToolbar" which is in my XUI xml file as you know.

package my_custom_toolbar

function init(win = current_window())
{
  if (window_state(win) < 0) {

    # As expected, the following line of code

    # fires when Arbortext is first started.
    response("Invalid window $win");
    return;
  }

  local doc = window_doc(win)
  if (!doc_valid(doc)) {
    response("Invalid document");
    return;
  }

  # Load my custom toolbar on Windows.
  local XUI_file = get_custom_dir() . "\\dialogs\\my-custom-toolbar.xml";
  window_load_component_file(win, XUI_file);
 
  # window_add_callback (window, cbtype, callback)
  ret = window_add_callback (win,'myCustomToolbar',WINDOW_LOAD);
  return win;
}
# Call the above function
init();

What is apparently happening is that the above code runs only once, and that's it. Even if I open a document for edit, it doesn't run again. Therefore, it can never reach the loading of my custom toolbar or the callback code. Could you please show me how to use the window_add_callback() function in this case? Also, could you please help me get unstuck from not having my code run more than once?

Your help is greatly appreciated Clay, thanks a bunch.

Regards,

- Giorgio

[ggrosso0321 · Accepted solution]

Hi Everyone,

I think I may have the solution for my issue. I wanted to load a custom toolbar when Arbortext is first started but I just couldn't do it. Thanks to Clay, and some information that I found on this site I was able to get it to work as I want. Now the question is ... did I do it properly?

Here's my ACL code:

------------------------------------------------
package my_custom_toolbar;

# Forward references
function reload_Toolbar(){}#<==I don't know if I really need this?

function init_toolbar(win = current_window())
{
  # Use a window callback to load the toolbar on callback.
  window_add_callback(0,'create','reload_Toolbar');

  return win;
}

# Function to actually load the toolbar.
function reload_Toolbar(win)
{
  # Load my custom toolbar on Windows.
  local XUI_file = get_custom_dir() . "\\dialogs\\my-custom-toolbar.xml";

  if(win && XUI_file)

  {
    window_load_component_file(win, XUI_file);

  }

  else

  {

    response("An unknown error has occurred while loading the window.");

  }
}

# Call the above function
init_toolbar();

-------------------------------------------------

And that's what I have. Clay please provide your input so I don't inadvertently give a bad example here.

Thanks,

Giorgio

[ClayHelberg]

Looks good to me, Giorgio! Nice work putting the pieces together.

[ggrosso0321]

Thanks Clay!

BTW, can these toolbars be colored with backgroundcolor="#1E90FF" type declarations in the XUI file? I tried it with one of the buttons on my toolbar, the toolbar element, and the window, but nothing worked.

-Giorgio