This Bugzilla instance is a read-only archive of historic NetBeans bug reports. To report a bug in NetBeans please follow the project's instructions for reporting issues.
The Help button on the proprety sheet is not behaving like is should. Previously, clicking the help button called the Help ID for whatever tab was fronted, no matter what was selected. Now the help button calls the tab help ID only if the category node is selected. Otherwise, the help ID for the node is called. For example, on filesystem prop sheet, select Capabilities and click Help and you get the Capabilities help page, select any of Capabilities contents and you get the filesystem node. This is important because: * Wrong help ID is being called * The Help button is enabled even if there is no prop sheet help The old tab help IDs should still be valid for each property, and if there is no help ID for the property sheet, the Help button should be disabled. Thanks.
I don't know if anyone has ever defined whether the help button should be disabled if the particular property doesn't have help, or if it should just show help on the node or general help if there's no more specific context. Not to mention I have no idea if there's a general property sheet help page, or what when or how that should get invoked. Anyway, I haven't done anything to this code in quite a while, but I'll take a look at it. So I know, what *should* be happening in the various places you mentioned? It would help if you could point out: - A property with a specific help ID for it, and what I should see if it's working right - A property with no explicit help ID for it, and what I should see then - A case where I should get the node help/property sheet help/whatever, and what I should see if it works right Honestly, it's never been well defined how this should work. I believe the current sequence when you press the help button is: - Look for help on the property - If none, look for help on the node - If none, display general help So, maybe I'm being dense, but I'd like to get nailed down exactly what should happen - is the above sequence right? Is the above sequence right but broken? Is the above sequence wrong but doing what it's programmed to do? And get some testable examples so that I can see what's broke and know when it's fixed.
I know this hasn't been defined very well. First off - there is no help for individual properties, so no individual property should have a Help ID. In the past, there was one help ID for each tab in the prop sheet. Now that those tabs have been turned into categories in the merged prop sheet (i.e., Capabilities on filesystems), both the category name (Capabilities) and all of its contents (all the Use In * properties) should have the same help ID. The reason why we need individual help IDs for the categories and not just one for each prop sheet are: * Additional modules may add a new category that needs Help. * For long property sheets, need to anchor each category to its description in the Help page. If no property has been selected yet, the Help button should call the help ID for the first category on the list, I suppose. If the category for the currently selected property does not have a help ID, the button should be disabled. It should never call the help ID for the node, window, or whatever. Right now, it is doing this: - Look for help on the property - If none, look for help on the node - If none, display general help But that's wrong. It should just call the category help ID or be disabled. Hope that's clear but it probably isn't :-)
Clear. Ugly implementation-wise since actually a property object has no idea what category it belongs to. So the thing is to avoid scanning the entire universe to figure out whom it belongs to just to decide if the help button should be enabled or not. I'd like to double check disabling the help button with the HIE guys - it's not visually obvious that it is associated with the selected property, and it lives in a component that also tracks the selected node.
Adding the UI keyword to get the HIEs in on the discussion. IMO the Help button should not be linked to the node help page when there is no property sheet help. It should just be disabled. The reasons are: 1. Most important nodes have property sheet help 2. Some nodes that don't have prop sheet help also don't have node help. For example, right now the Help button is active on folder node property sheet. Since folder nodes have no prop sheet or node help, you get the help page for the Explorer, which has absolutely nothing to do with the prop sheet. 3. The Help button was designed to be done specifically for the prop sheet. Anyway, I need to make arrangements with other developers to add prop sheet help IDs. Are there any instructions I can pass on to them on how to correctly hook up each category of help IDs?
I discussed this with Patrick and it looks like assigning help IDs by category will not work. We want to have one help page that lists all the properties in each tab of a node's property sheet. But Capabilities has the org.openide.filesystems.FileSystemCapability.Bean help ID no matter whether it is in a VCS filesystem, regular filesystem, or JAR. So it looks like we will need to have one help ID per tab in a property sheet. The prop sheet Help button should therefore search in this order. 1. Individual property. 2. Property sheet tab. 3. If neither are present, disable.
So why not just explicitly put the right id into each of the filesystem capabilities properties, so they all point to the same place anyway? If the property sheet will be checking for per-property id's, that should work fine.
"We want to have one help page that lists all the properties in each tab of a node's property sheet." Requesting clarification from the writer :-) Does the above sentence mean you want one help page per node, or one help page per property set (formerly a tab, sometimes a tab in the form editor)?
We need one help ID per property set (formerly a tab, sometimes a tab in the form editor).
John, I don't think this is clear. I thought we agreed that we need an ID per new tab. I'm not sure what "property set" means.
As I'm understanding it from Tim, property set means property tab. They're not really tabs any more since the tabs have been replaced with toggle buttons on the top. Tim, do you understand what I mean?
Okay, this is all getting a little confusing. What is a tab now? I'll explain my part, you explain yours :-) A property set is, programmatically, a set of properties (fancy that). So in the NetBeans world, it works like: PropertySet[] someNode.getPropertySets(); Property[] someProperty.getProperties(); Each expandable doohicky in the property sheet represents a PropertySet. Then, to make things more confusing, to support tabs for the form editor, we let each property set supply a "tab name". Normally this is null, and they all show up together in the property sheet. For the form editor, some Property Sets provide names like "events", etc. So if the property sheet finds any tab names, it will put all the sets that return the same tab name on their own tab. So the thousand dollar question is: If I have the following in the property sheet: -------------------------------------- Property set A -------------------------------------- Property 1 | Value 1 -------------------------------------- Property 2 | Value 2 -------------------------------------- Property set B -------------------------------------- Property 3 | Value 3 ____________________________________________ Is the help ID - The same for Property 1 and Property 3? - The same for Property 3 and Property Set B? - The same for Property Set A and Property Set B? And, if in the form editor, we also have tabs: [ Tab 1] [Tab 2] [Tab 3] [Tab 4] -------------------------------------- Property set A -------------------------------------- Property 1 | Value 1 -------------------------------------- Property 2 | Value 2 -------------------------------------- Property set B -------------------------------------- Property 3 | Value 3 ____________________________________________ is the help ID - The same for everything on the tab? - The same as above? Please include as many circles and arrows as possible in your response :-)
What I can do fairly painlessly is the following - when F1 is pressed on a node: - Check the property for a help ID - If none, check the property set that owns it for a help ID - If none show the node help (or maybe disable help button - up to HIE
OK, thought we were on the same page with this property set thing but we aren't :) We need one help ID per tab in the property sheet. If the property sheet has no tabs, we will assume that it really just has one default tab and assign one help ID to all the properties in the sheet. This is so that if another module adds another tab, that tab can have a different help ID than the original "default tab". So for your first example: -------------------------------------- Property set A -------------------------------------- Property 1 | Value 1 -------------------------------------- Property 2 | Value 2 -------------------------------------- Property set B -------------------------------------- Property 3 | Value 3 ______________________________________ We need one help ID for *all properties* in this property sheet. And for your second example: [ Tab 1] [Tab 2] [Tab 3] [Tab 4] -------------------------------------- Property set A -------------------------------------- Property 1 | Value 1 -------------------------------------- Property 2 | Value 2 -------------------------------------- Property set B -------------------------------------- Property 3 | Value 3 ______________________________________ We need separate help IDs for Tab 1, Tab 2, etc. Just setting the help IDs on property sets does not work, because these property sets are shared between nodes. As I mentioned before, if you select a property in the Capabilities property set and click the Help button, how will the IDE know whether to show the help page for VCS filesystem, Archive filesystem, or local filesystem? The property set would have to set its help ID dynamically to indicate what type of node it was representing. But it seems much easier to just give one help ID to the whole property sheet tab and not bother with mapping lots of individual property sets to the same page anyway. Hope that's clear. Probably isn't :-) And we talked with help writers for other IDE products last night (RAVE, Studio) and they were pretty unaminous that if the property sheet does not have help, the Help button should be disabled. Node help should not be shown.
> As I mentioned before, >if you select a property in the Capabilities property set and click >the Help button, how will the IDE know whether to show the help page >for VCS filesystem, Archive filesystem, or local filesystem? The effect of Capabilities is exactly the same even if the filesystem is stored by passenger pigeon on the moon. Why on earth would we want to show the user anything but documentation on what that does when the look for help on it? > And we talked with help writers for other IDE products last night > (RAVE, Studio) and they were pretty unaminous that if the property > sheet does not have help, the Help button should be disabled. Node >help should not be shown. I'm not at all surprised at that - to a doc writer, the help button is help on the property sheet, and it's a no brainer. Profesionalni deformace. To a *user*, it's the only help button in the main window, separated by a splitter that looks pretty much like all the other splitters in the main window. *You* know it's help for the property sheet, and it's obvious because you asked for it to be there. It's not necessarily at all obvious to someone who is just looking at the main window and doesn't know that.
> The effect of Capabilities is exactly the same even if the filesystem > is stored by passenger pigeon on the moon. Why on earth would we want > to show the user anything but documentation on what that does when the > look for help on it? The problem is that the user getting the Capabilities topic may then want to surf through "see also" links in the help topic, but we have no effective way of knowing what kinds of objects the user might have access to, and thus which help topics to link to from that page.
When the user clicks the Help button on the property sheet, I think she wants to see a help page listing all of the properties on that property sheet. If we just do help IDs by property sets, then she can't do that. She can see one page on the Capabilities property set, one page on the Sorting property set, then one more page on the property sets that are specific only to that type of filesystem. We could go on and on about this, but the docs department has decided that the style we're going to implement for all IDEs is that all of the properties on each tab of the property sheet are to be documented on one Help page. We're asking you to please provide a mechanism that makes that possible. I'm open to other ways of implementing it if you have any suggestions, but I don't want to change IDE-wide docs guidelines a few weeks before the release.
The fly in all this copious ointment is: If a tab's contents is composed of 3 property sets, which property set should I get the help ID from? If you want them per-tab rather than per-property set or per-node, we need an API for that (which is simple enough and will take about 30 second to implement). But everyone providing more than one property on a single tab is going to have to supply these help IDs before 3.6 is released. The good news is that only the form editor uses tabs at all, so they're the only ones who would have to do this. Last question: In the diagram above, you stated that a property sheet with multiple sets of properties, but no tabs would have the same help ID no matter which property was selected. Is that help ID the same one as the Node's help ID? Or is there a consistent way to take the Node's help ID and stick some text on the end of it to derive it, which will work everywhere?
Thought about that as well. Don't want to make everyone rewrite the help IDs for every property sheet :-/ Let's just take the help ID from the first property set in each "tab" and make that the help ID for the whole tab. That way the existing help IDs still work. The prop sheet should ignore the help IDs that are set on the other property sets, however.
and just to be excruciatingly explicit, "ignore the IDs set on the other property sets" means that the ID for the first property set will be used, even if a property from another property set in the same tab is selected.
Exactly.
Okay, it's fixed as requested. It will look for a help id - on the selected property - on the first displayed property set - on the node, for a special property "propertiesHelpID" John, what you need to tell the folks who need to implement this is: They should return a String from Node.getValue("propertiesHelpID") with the help id that should be used for the *properties* of the node (not the node itself). I will get this into the openide documentation with a later commit. Note that the result of this change is that right now, the help button is disabled *almost all the time* - java class subnodes were the only things I found that had help id's on their property sets, poking around at random. I presume you intend to fix that.
Thanks Tim. Actually, this worked pretty well. The Java and Form nodes actually didn't have help IDs for their first propertySet, so that worked as it should. I will file issues to add helpsets. Filesystems nodes, Java subnodes, and Ant targets all work. The only anomaly is the Ant script node, which had a help ID for its first propertySet but is for some reason not activating its help button. I'll file an issue about that as well. Thanks again.
forgot to mark as verified