How do I use the Project Browser?
This lesson shows you how to use the features of the Project Browser to explore and modify your LiveCode applications.
The Project Browser was introduced into LiveCode at release 6.0.0 and provides an updated and automatically refreshed view of the visual aspects of your LiveCode projects. It replaces the Application Browser, which is present in all earlier versions of LiveCode. The Project Browser allows you to have direct visibility of key aspects of your application in a hierarchical form, without having to navigate from one card to the next.
This lesson provides an overview over the key functionality but does not go into the detailed aspects that are generally intuitive and self evident.
The Anatomy of the Project Browser
The Project Browser provides many features. We list the key visible ones here under points 1 - 8:
1. The cog that takes you to the Project Browser preferences.
2. Expansion and contraction arrows that allow you to dig down into expandable parts of the stack that are being represented.
3. The type and names of the control that is being displayed in the Project Browser.
4. The number of lines of code that are associated with the control.
5. An eye and lock that allow you to show/hide the control or lock/unlock it from being edited.
6. A number of alignment operations that help you specify where controls are to appear on the cards.
7. Grouping, duplication and deletion fields.
Sample Stack Data
The sample stack shown here consists of three cards. Two cards have buttons on them as shown here. The other card has no controls on it.
The card on the left has two buttons that intersect. The top left button is lying beneath the button on the bottom right. The former button is on layer 1 and the the latter button is on layer 2. The first button contains a short mouseUp handler that answers some text through a dialog box.
The card on the right has a single group on it that contains four radio buttons.
The structure of the test stack shown here is clearly visible in the hierarchical representation that is displayed in the Project Browser in the previous step.
Throughout the rest of this lesson we use this basic stack to demonstrate features of the Project Browser.
The Project Browser preferences are accessible via the cog which is shown at the top left hand side of the Project Browser. You can also access them from LiveCode Preferences, Project Browser.
You can choose whether to represent objects by text or by icon, you can show sections according to types of script, stacks, or stacks in use, you can sort stacks, cards and controls in different ways, and you can choose the text size.
You can rename controls with the Project Browser by double clicking on the name of the control that is to be renamed. This opens an edit field in which you can enter a new name or modify an existing one. The field will resize to fit the name when you are done.
Accessing the Script
The Project Browser gives you instant visibility of the number of lines of code that are associated with each control. The number of lines are displayed in the boxes on the right hand side next to each control. You can click on these boxes to open the script editor and display the code for the particular control.
Accessing Behavior Scripts
The Project Browser allows you to easily edit behavior scripts associated with controls. The index of the behavior script appears in an oval next to the number of lines in the control script. Clicking the oval will open the behavior script.
If a behavior itself has a behavior this will also be shown in the Project Browser as an oval with an increasing index for each behavior. These are called chained behaviors.
The layer of a control determines how deep in a stack of controls the control appears. Layer 1 is the lowest layer and is the one that sits directly on top of the card. Controls on lower layers are covered by controls that lie on higher layers. If you look back to step "Sample Stack Data", you can see that the top left button is covering the bottom right button.
This layering hierarchy can be controlled and changed in the Project Browser by rearranging the order in which the controls are displayed. You can drag and drop controls around the Project Browser in order to change the layer on which they appear. This example shows how to drag and drop a control above another. You can see that the top left button now lies on top of the bottom right button.
You can duplicate one or more controls by selecting them in the Project Browser and pressing the "Create new control" (1) or "Clone control"(2) button. "Create new control" allows you to duplicate the specific control types you selected but does not copy any of the parameters you set on the controls you are copying. "Clone control" allows you to duplicate the controls that are selected and the content that was set up in the controls. This also includes the code that may be associated with a control. Here I have selected the Radio button group, and cloned it. A new group has been placed on the card.
You can align control, using the alignment options on the bottom left of the Project Browser. In this example we are centering controls horizontally. You could now distribute the controls further, either manually or by selecting other combinations of automatic alignment.
You can hide controls or groups of control by clicking on the eye that is displayed on the right hand side next to a control. This example shows how the second group of radio buttons can be hidden.
I'm going to start using LiveCode soon, so I'm surprised this wasn't already there from the start. It looks like an invaluable tool. Well, done for putting it in there. Thank you!
I'm a beginner, but my project browser is full of projects that aren't mine: revcursors, revcore, messagebox, etc.
How can show only my project?
yes, you may see a number of items that you did not write but are legitimately there. These are mainly stacks that control or run the IDE. You can switch the view of these off by un-ticking: "View->LiveCode UI Elements in List".
This description incorrectly mentions "property browser" instead of "project browser" a few times. Please check!
Hi Gert, thanks for pointing this out, the text in this lesson has now been updated.
I am using LiveCode 7.0.6 commercial edition. In the Project Browser (as well in the Application Browser and in the Properties Inspector), I see all active Rev Stacks beside my own Stacks. Such as revApplicationOverview, Answer Dialog, and many others.
The settings of the Preferences does'n help to change the picture.
Can you, please, suggest, what might help to see ONLY the current elements of my Stacks in the LiveCode Tools' lists? Especially, that in the previous LiveCode versions everything was all right with this.
You can stop the rev stacks appearing by turning off the "LiveCode UI Elements in lists" option in the View menu.
I hope that helps.
Thank you very much, dear Elanor! It works!
How can I get the Project Browser to show when I start Livecode?
To open the Project Browser, go to the Tools menu and choose "Project Browser." I do not think it is possible to set a preference to open it by default when LiveCode is opened.
In the current version 9.0.x there is an extra icon that appears to the left of the lines of code count. The number appears in an oval, but only a few of my objects have it. Can this article please be updated to explain what it is?
The oval you describe show behavior scripts for a control. Clicking on it will open the behavior script. For example DataGrids have behaviors and these will show in the Project Browser.
I have added another section to this lesson explaining how behaviors appear in the Project Browser.
Thanks for bringing this to our attention.
Instead of a "+" (or a "-" after the "+" contraction arrow is clicked), sometimes I see a solid dot or circle in the Project Browser. Clicking it appears to have no visual effect. What does the dot signify?
Hi Monty May
The solid dot means that the control does not have any children so there is nothing to expand, for example a new card with no objects. It should only appear for controls that can be containers e.g. cards, groups etc. If you are seeing it for other types of controls that might be a bug, if that is the case we would appreciate it if you could report it.
I close a project and confirm to the dialog box to purge the stack and all its objects from memory. When close the Project Browser and open it again the stack is still there. Is there a way to clear the memory is script?
What method are you using the close the stack, I have tested setting the "Purge stack on close" and "Purge window on close" properties of the stack and using the "Close and remove from memory" option in the Project Browser and both remove the stack from memory and the Project Browser.
If you can let us know a bit more about the method you are using we will look into it.