Documentation for Dialog Toolkit

AppleScript Dialog Toolkit
#1

Shane,

I started doing some documentation on how to use Dialog Toolkit to make it more accessible to the average scripter not familiar, or only somewhat familiar, with ASObj-C. I’m probably half way through it by now. I just wondered what you thought of it.

Comments are welcomed by anyone who has any thought on this. Dialog Toolkit is a very powerful tool to use as long as people can figure it out. I’d like the documentation to be something that a person somewhat new to AppleScript can follow but still be handy quick reference for someone very familiar with Applescript. My thought is to have both power user sections and beginner sections in the manual but separated so a person can read it comfortably whatever their experience is with AppleScript or ASObj-C.

I included a zipped pdf of the documentation I’ve done so far in this post.

Bill

How “display enhanced alert” works.pdf.zip (54.4 KB)

#2

I finished the line by description of how “display enhanced alert” works. I added the description and the source code with the line numbers to the book. I turned the source code 90 clockwise on the page or it would look really bad and be hard to read. The page is too narrow the other way. The goal it to have a line by line description of all the handlers involved as well as description of how to put it all together even if you don’t know a thing about ASObj-C.

It would be great if anyone notices an error in what I did to let me know or if you think the book is terrible I would be interested in what’s terrible. I think this project is really work while. AppleScripters have gotten by with terrible dialog choices for a long time and I’d like to see that change.

Bill

How “display enhanced alert” works 1.0.1.pdf.zip (107.6 KB)

#3

I thought there would be some interest in documentation for Dialog Toolkit. But there doesn’t seem be any so I’m going to discontinue my efforts to document it. I already know this stuff so there isn’t much point in documenting it for myself.

Bill

#4

well, allowing for the fact that it’s only been a day…it’s less documentation that helps use NSAlert and more of a list of NSAlert components. There’s nothing that actually shows how the components are used in a standard alert vs. an “enhanced” alert.

As well, it looks like as it is, it’s not allowing for changes in the NSAlert API. For example, you reference NSWarningAlertStyle, NSInformationalAlertStyle, NSCriticalAlertStyle, but those are all deprecated, or about to be, so any documentation on NSAlert should account for that.

There’s also information that while interesting, is not directly useful to someone learning to use NSAlert. For example, under “Supression Checkbox” you have:

(The variable “TheAlert” holds a pointer to the Alert data structure in memory)

But nothing about why knowing that is important to the person reading this bit of documentation. If there’s no need to know that other than “Hmm…that’s interesting”, why have it in there? If there is a need to know, then that should be explicitly stated so the context is clear.

If this is supposed to help someone become familiar with NSAlert so they can use it in their code, then as it currently stands, it’s not going to do that very well.

#5

Thank you for your reply. My first goal was to document what’s in Dialog Toolkit. It seemed the natural first step towards saying how it works and then I would talk about how to use it. I had thought about examples of how to use it as going in last but in light of your comments perhaps that was a bad idea.

I first posted on this subject a while ago. The 2 post that show up today are only the last 2 posts. Once a post gets old enough it doesn’t show up anymore. You make a lot of good points. I’ve worked with appleScript for a long time and some things just become automatic for me. I just don’t think about them anymore. It is helpful for someone to point out all the oversights in the documentation that don’t explain things, or explain things well enough. Everything you said was great input.

If by saying “standard alert” you mean NSAlert and by saying an “enhanced alert” you mean Shane’s library then the “enhanced alert” uses NSAlert to display an enhanced alert. What makes the “enhanced alert” enhanced are the capabilities added by Shane’s library (i.e. “Dialog Toolkit”) and the fact that working with Alerts are simpler when using “Dialog Toolkit.” I was not targeting this documentation to just working with NSAlert without using “Dialog Toolkit.” Doing that would limit what could be done and would be more complicated to code.

You have a point about saying “TheAlert is a pointer.” I included that to point out it was a pointer and not the actual alert. It makes a difference in how the alert is referenced.

NSWarningAlertStyle, NSInformationalAlertStyle and NSCriticalAlertStyle are all used in the official documentation from Apple for NSAlert. I wasn’t aware they were deprecated. It doesn’t say that in NSAlert documentation. But the AppKit documentation says it’s deprecated. Deprecated does not mean it doesn’t work any more but it’s a sign that it can be dropped at anytime in the future.

I looked up NSAlert in the AppKit reference at
https://developer.apple.com/reference/appkit/nsalert?language=objc

Then went to NSAlertStyle at
https://developer.apple.com/reference/appkit/nsalertstyle?language=objc
and found they have beta testing constants (enumerations) listed: NSAlertStyleCritical = 2, NSAlertStyleInformational = 1, NSAlertStyleWarning = 0.

The old constants (enumerations) were NSCriticalAlertStyle = 2, NSInformationalAlertStyle = 1, NSWarningAlertStyle = 0. So the actual numeric values will stay the same, but name of the constants will be changing after the beta test is over.

Changes in the NSAlert API would involve overriding things in the methods or objects. That was more then I was thinking of, but there are many ways to implement the Dialog Toolkit which uses NSAlert. What I mean by ways to implement the Dialog Toolkit is knowing enough to be able to change things inside dialog toolkit to fit a special need.

Something like that is best done by creating your own special case handler to perform the special tasks. The reason I say that is when Shane comes out with an update for “Dialog Toolkit” it won’t turn into a nightmare trying to reintegrate your change into the new library. All that is required after a toolkit update is to fix any bugs that come up when the special case handler interfaces with a handler in “Dialog Toolkit.”

The best practice for modifying an existing library is to change as little as possible to get the job done and to keep those changes contained to as small an area as possible, especially when the library (“dialog toolkit”) is being updated from time to time. But using the library requires some understanding of what’s going on inside “Dialog Toolkit” and modifying the library requires a lot of understanding of what’s going on.

This is a big project to write this book to cover the different experience levels of scripters and I can see it is bigger then I expected when I started. I haven’t even started on the “how to do something” part yet.

Writing such a book is often only as good as the input from people reading the book. If you or anyone else reading this sees something that’s missing feel free to tell me.

With all that said is this kind of documentation something you would be interested in having? I rate whether doing this as being worth my time by people posting something about the project so I know there is some interest.

Bill

#6

FWIW, this renaming of enums happened in El Capitan, and there are other examples in Sierra. It’s all to do with moving to a more consistent naming convention that fits better with Swift. But it is a bit of a trap for ASObjC, because ASObjC code is evaluated at run-time, not compile time. This means that if you use the latest enum, you’ll get an error if the script is run on 10.11 and earlier.

So there are a few solutions. First, the old versions may not disappear for a while, so you can keep using the old version. You can also use the integer equivalents, although that’s a recipe for unreadable code.

But if you use Script Debugger’s code completion, and choose Use Properties for Cocoa Terms, you’re covered both ways. The integer value is inserted in the property, so it no longer matters if the enum changes, and the property makes the code still readable.

#7

I’m obviously interested. However, (a) I’m also a bit snowed under at the moment, and (b) I really hope to give Dialog Toolkit a drastic makeover at some stage. Although it works, I wrote the original a long time ago, and like anything else, I can now see how it can be improved considerably. It just takes time.

So you might want to factor that into things. Unfortunately I can’t say when it will happen, other than not in the immediate future.

#8

Shane,

I wasn’t thinking of you when I thought no one was interested. I am very aware of how busy you are. So I am doing the documentation for you since I can do that. 3 example scripts isn’t enough documentation to get people going that don’t have enough pre knowledge. I can update the documentation when “Dialog Toolkit” is updated. Expanding the capabilities of “Dialog Toolkit” is something I would wait until you have time : ) I don’t know enough to even start that. I should be able to answer some basic questions on “Dialog Toolkit.” But since you told me your interested I’ll finish the manual. I was planning on giving the whole thing to you when I’m done if you want it.

The latest thing I did for the manual is give it a less stupid name : ) It was the first name that came to mind. I added blue text to the start of each chapter about when, and if, it’s ok to skip the chapter. It’s part of making it for different levels of users. I also added a “What is Dialog ToolKit” to the front of the manual.

I had already looked up the problem with NSWarningAlertStyle, NSInformationalAlertStyle and NSCriticalAlertStyle and updated the manual after jcwelch brought up the problem.

The next thing I’ll add is how to write the script to use “display enhanced alert.” The documentation already says what things get added to the control list just before calling “display enhanced alert.” That’s gotten some people mixed up. I know it’s just the NS stuff that gets added but I was really specific in the manual.

I did post the latest version. If you don’t have time to read it it no big deal.

Bill

Using “display enhanced alert”.pdf.zip (111.1 KB)

#9

Maybe somebody would be interested to know that I added some features to Display Dialog Toolkit

display enhanced alertWithoutShortcut
which, as the name states disable the shortcuts linked to Cancel and OK buttons.
It’s interesting when we have alerts with text fields.
Complementary feature, its popups return not only the title of the selected item but it returns the index of this one, and accept the index of selected item on entry.

create centered field
create centered text fields

create popupWithDefault
create popups for which the item selected on entry is not necessarily the first one.
These popups return the title and the index of the selected item.

create labeled popupWithDefault
as above but with a label

create matrixWithDefault
create groups of radio buttons for which the item selected on entry is not necessarily the first one.
These groups of radio buttons return the title and the index of the selected item.

create labeled matrixWithDefault
as above but with a label

height for label
return the height of a given label. May be useful when a label may wrap.

max width for labelsSmallSystemFont
return the width of the message passed as theExplanation

Yvan KOENIG running El Capitan 10.11.6 in French (VALLAURIS, France) samedi 13 aout 2016 17:14:56

1 Like
#10

Your additions to dialog toolkit are create ideas. They all only require minor changes but return some nice improvements. That is difficulty, thinking of things that don’t require redoing a lot or most of dialog toolkit but still provide nice improvements. I’ll add those features to my dialog toolkit and I can put examples of what I come up with to do it to the manual I’m doing. I’ll give you credit in the manual and say koenigyvan came up with the ideas.

Ideas like this are great for helping everyone : )

Thanks for the great ideas : )

Bill

#11

Hello Bill:

If you made changes, it would be fine to send me a copy of them.

I’m puzzled. On Sun, 14 Aug 2016 11:21:20 +0200 (CEST) I tried to respond to you personal message with two screenshots.
Today I received a message starting with :
This is the mail system at host msfrf2618.sfr.fr.

I’m sorry to have to inform you that your message could not
be delivered to one or more recipients. It’s attached below.

For further assistance, please send mail to postmaster.

If you do so, please include this problem report. You can
delete your own text from the attached returned message.

May you explain what was wrong and how I may send you the screenshots.

Yvan KOENIG running El Capitan 10.11.6 in French (VALLAURIS, France) mardi 16 aout 2016 12:41:43

#12

I have made changes to the manual since. I wrote, added and explained the 3 handlers you talked about. I am writing a bigger manual that deals with everything a person needs to know to use Dialog Toolkit. I added a glossary to the manual. The manual gets into ASObj-C, how to read Apple documentation and other things not added yet. I’m also trying to make the manual usable for people with different experience levels. Everyday I do a little more in my spare time.

Here is the zipped version of the latest version of the manual.

About the screen shot problems, host msfrf2618.sfr.fr sound like a mail server in France. There is no indication of what the problem is. It would be a lot easier to just upload it to the group. There is an “upload” button on the page just above where the message is typed. The icon looks like like a long skinny rectangle with an upward pointing arrow coming out the middle. Apple screen shots are a PNG image type and they can’t be uploaded to the group in that form. But you can upload anything compressed into a zip file. So the easiest thing to do is to select the screen shots in Finder and choose the “Compress” menu item from the “File” menu. When more then 1 item in Finder is selected this menu item changes. For 2 selected files the menu item would be “Compress 2 items.” Then just upload the newly created file that ends with “.zip”

Bill

Using “display enhanced alert”.pdf.zip (323.9 KB)

#13

Yvan, your enhancements look good.

How do we get a copy?
Do you have sample scripts that show your new controls?

#14

Hello Jim.

I was at hospital for an heavy surgery task.
i just returned at home so please accept apologizes for this delay before responding.
I’m not sure that my brain is clear enough to enter Applescript before few days so you will have to wait a bit before receiving a more precise answer.

Yvan KOENIG running Sierra 10.12.6 in French (VALLAURIS, France) lundi 4 septembre 2017 10:32:36

#15

Yvan,

Tous mes voeux de bon rétablissement.

:wink:

#16

Yvan, it is good to have you back. I hope everything went well with your surgery, and that you fully recover very soon.

Please do not worry about my request. There is no rush. Whenever you feel up to dealing with it will be fine.

#17

@koenigyvan

Yvan, if you don’t mind sharing, I’d still love to see sample scripts and script lib of your new controls.

#18

Is “Display Toolkit” the same as “Dialog Toolkit”?