issue-#100 Controls documentation

User avatar
Robert
Posts: 1024
Joined: Sat Sep 28, 2013 11:04 am
Location: Edinburgh, Scotland

Re: issue-#100 Controls documentation

Post by Robert »

How about:
Pressing a push button (also called a command button) invokes a BlackBox "Command". A Command is frequently an exported parameterless Component Pascal procedure, but it may be any sequence of procedure calls that comply with the syntax described in the Docu for StdInterpreter. The individual procedures called may be either constant (or normal) procedures, or procedure variables.
User avatar
Robert
Posts: 1024
Joined: Sat Sep 28, 2013 11:04 am
Location: Edinburgh, Scotland

Re: issue-#100 Controls documentation

Post by Robert »

I am guessing - please correct me if I am wrong - but I suspect the idea of "Command" comes from Oberon, where it was a simple parameterless procedure. Calling Commands conveniently was recognised as a very valuable feature, and was generalised by Oms who kept the term Command for historical reasons. Or maybe not ...
User avatar
Josef Templ
Posts: 2047
Joined: Tue Sep 17, 2013 6:50 am

Re: issue-#100 Controls documentation

Post by Josef Templ »

Robert wrote:How about:
Pressing a push button (also called a command button) invokes a BlackBox "Command". A Command is frequently an exported parameterless Component Pascal procedure, but it may be any sequence of procedure calls that comply with the syntax described in the Docu for StdInterpreter. The individual procedures called may be either constant (or normal) procedures, or procedure variables.
Excellent with one addition: the 'link' field is no longer mentioned.
The command is specified in the 'link' property of the control and this is special for push buttons
and does not quite match the generic description of the link property.
In the original there was a subtle hint to the link field by using the formulation "... linked to a parameterless exported procedure". A possible solution would be to change

... invokes a BlackBox "Command"...
to
... invokes the linked BlackBox "Command"...


Yes, It is almost certain that the term Command came from the original Oberon system.

- Josef
User avatar
Robert
Posts: 1024
Joined: Sat Sep 28, 2013 11:04 am
Location: Edinburgh, Scotland

Re: issue-#100 Controls documentation

Post by Robert »

The Docu for StdLinks uses the phrases "a command" & "command sequence".

Neither phrase is precisely defined. I suspect that both also refer to a StdInterpreter "Command", but this not explicitly stated.
Ivan Denisov
Posts: 1700
Joined: Tue Sep 17, 2013 12:21 am
Location: Russia

Re: issue-#100 Controls documentation

Post by Ivan Denisov »

So shall we rename the Controls -> Insert Command Button to Controls -> Insert Push Button ? And the documentations for Forms ?
User avatar
Robert
Posts: 1024
Joined: Sat Sep 28, 2013 11:04 am
Location: Edinburgh, Scotland

Re: issue-#100 Controls documentation

Post by Robert »

Ivan Denisov wrote:So shall we rename the Controls -> Insert Command Button to Controls -> Insert Push Button ?
Personally I prefer the term "Command Button".

You can say it is a Push Button, and what it does is call a BlackBox Command.

I don't think that I push on these Buttons, I think I click (or control / modifier click, or whatever) on them. So, to me, the term Push is unnatural.
User avatar
Josef Templ
Posts: 2047
Joined: Tue Sep 17, 2013 6:50 am

Re: issue-#100 Controls documentation

Post by Josef Templ »

For me it is perfectly OK to stay with Command button and explain that Push button is an alias for it,
very much as it was before in Controls docu.
I definitely would not change it throughout the whole system.

I think the name Push button came from the 3D animation of a button.
When pressed it appears as being pushed towards the surface,
like a real physical button.

With more modern GUI designs this behavior disappeared at least on some platforms
and the buttons are flat now.

- Josef
User avatar
DGDanforth
Posts: 1061
Joined: Tue Sep 17, 2013 1:16 am
Location: Palo Alto, California, USA
Contact:

Re: issue-#100 Controls documentation

Post by DGDanforth »

I just did 2 searches through the documentation

"push button" - 2 files (Obx/Docu/Address2.odc, System/Docu/Controls.odc)
"command button" - 18 files

Hence I would vote for remove "Push Button" from Controls and replace it with "Command Button"
BUT that changes the interface of Controls and could cause user programs to crash.

Why did Oberon Microsystems introduce the term "Push Button" when the rest of their documentation uses command button?

There are 6 modules in the framework that refer to PushButton.

Location
Ctl/Mod/MSForms.odc
PushButton [2]
Ctl/Mod/PowerPoint9.odc
PushButton [46]
Form/Mod/Gen.odc
PushButton [2]
Host/Mod/CFrames.odc
PushButton [19]
Std/Mod/CFrames.odc
PushButton [5]
System/Mod/Controls.odc
PushButton [26]

6 Files found
14 Dirs searched
263 Files searched
0.5 Search time

So, how do we want to handle this?
-Doug
User avatar
DGDanforth
Posts: 1061
Joined: Tue Sep 17, 2013 1:16 am
Location: Palo Alto, California, USA
Contact:

Re: issue-#100 Controls documentation

Post by DGDanforth »

There really is an inconsistency in the frameworks documentation when it comes to
Command Button and Push Button.
Here is what Tut-4 says
CommandButton.JPG
Controls.odc is the source of the problem.

How about this

Code: Select all

		CommandButton = POINTER TO RECORD (Control) END;
		
		PushButton = CommandButton;

Code: Select all

				WITH f: StdCFrames.Caption DO lbl := f.label$
				| f: StdCFrames.CommandButton DO lbl := f.label$
				| f: StdCFrames.PushButton DO lbl := f.label$
				| f: StdCFrames.RadioButton DO lbl := f.label$
				| f: StdCFrames.CheckBox DO lbl := f.label$
				| f: StdCFrames.Group DO lbl := f.label$
				ELSE lbl := c.label$
				END;

Code: Select all

	PROCEDURE (d: Directory) NewCommandButton* (p: Prop): Control, NEW, ABSTRACT;
	PROCEDURE (d: Directory) NewPushButton* (p: Prop): Control, NEW, ABSTRACT;

Code: Select all

	PROCEDURE (d: StdDirectory) NewCommandButton (p: Prop): Control;
		VAR c: CommandButton;
	BEGIN
		NEW(c); OpenLink(c, p); RETURN c
	END NewCommandButton;

	PROCEDURE (d: StdDirectory) NewPushButton (p: Prop): Control;
		VAR c: PushButton;
	BEGIN
		NEW(c); OpenLink(c, p); RETURN c
	END NewPushButton;

etc.
StdCFrames also needs slight modification.

By making those changes to the source code we do not break users code and it allows them to
move to using CommandButton instead of PushButton. It also allows the Controls documentation to be in accord with the
bulk of the framework documentation.
-Doug
User avatar
Josef Templ
Posts: 2047
Joined: Tue Sep 17, 2013 6:50 am

Re: issue-#100 Controls documentation

Post by Josef Templ »

The Windows API uses the term Push button.

In general, this is not an important question at all. So far, nobody cared
and we can live with an alias name very well, if it is defined as such.

Keep the changes to a minimum or we will never finish issue-#100.

- Josef
Post Reply