Advice/Guidance Needed With Our Freepascal Wiki

[Aruna]

Hi, I started dabbling with the wiki.I can use some help in understanding how to separate two sections.I am not a Wikimedia expert. I am a total newbie.
I was searching for information and example code for Canvas.Rectangle on the wiki and I felt there was a need to bring things up to date? So I decided to do something about it.

You can see what I have done here:
Canvas.Rectangle

The difficulty I am having is separating the two sections clearly. I am not sure if I am explaining this clearly. I would also very much appreciate your thoughts and comments on if this will be useful or if I am simply wasting my time 

Maybe I should split things up into separate pages? What does everyone else think? I would like to 'clearly' separate the content from where it says 'Another Example'

[wp]

You can use section headings to separate chapters. See https://www.mediawiki.org/wiki/Help:Formatting

BUT: I really don't like to see drawing commands in a button OnClick handler. It leads to lots of issues for the user (*), and we here in the forum will have to answer user questions why such bad code is in the wiki. Please rewrite the section so that the code is in the Form's (Paintbox's, Panel's) OnPaint event - that's where drawing code must be executed!

(*) Explanation: Run the wiki's ButtonClick code --> The application will crash in some operating systems here (I think: mac). In the other operating systems the drawing is displayed fine, but you will have the issue that when the user drags another form over it the drawing will not be regenerated at the places covered. Or: Minimize the application and then restore it --> the drawing will be gone. This is because the form does not know how to redraw the rectangles. Only code in the OnPaint handler can be executed correctly whenever the OS needs to redraw a window.

[Aruna]

You can use section headings to separate chapters. See https://www.mediawiki.org/wiki/Help:Formatting

Thank you @wp

BUT: I really don't like to see drawing commands in a button OnClick handler. It leads to lots of issues for the user (*), and we here in the forum will have to answer user questions why such bad code is in the wiki. Please rewrite the section so that the code is in the Form's (Paintbox's, Panel's) OnPaint event - that's where drawing code must be executed!

I wanted to keep it simple. This is why I stuck with just the form. Adding a component is extra overhead but if that is the way to do things by all means so be it. So let me get this right, do not use click events, and do not draw directly on the form. Correct? I will change the code @wp no worries and thank you for explaining I did not know.

(*) Explanation: Run the wiki's ButtonClick code --> The application will crash in some operating systems here (I think: mac). In the other operating systems the drawing is displayed fine, but you will have the issue that when the user drags another form over it the drawing will not be regenerated at the places covered. Or: Minimize the application and then restore it --> the drawing will be gone. This is because the form does not know how to redraw the rectangles. Only code in the OnPaint handler can be executed correctly whenever the OS needs to redraw a window.

Understood and much obliged.

[Martin_fr]

You are aware that there is actual documentation for classes? Outside of the wiki...

https://lazarus-ccr.sourceforge.io/docs/lcl/graphics/tcanvas.rectangle.html

Sources for those docs are in the Lazarus distribution (also available as help files with F1). And corrections can be submitted as merge-request or patch against the git repository.  Files can be edited using fpdoc. (several utilities available, including one build into the IDE)

You can still add content to the wiki, like usage examples and what it will look like.

[Aruna]

You are aware that there is actual documentation for classes? Outside of the wiki...

https://lazarus-ccr.sourceforge.io/docs/lcl/graphics/tcanvas.rectangle.html

Yes I am @Martin_fr thank you for the link. When I was searching for documentation sure it was all there but never everything I needed to know in one single place.

Which made my life hard. This is the simple reason I thought what if I start from the function/method signature then show how it is broken down so the user understands how to call it with the correct types of parameters then give them some code and a screenshot of how it will look. Simple, all you need in one place and fully documented.

I am going to use what @wp just taught me about when you minimize the form and then restore it you lose the drawing. So why not give the reader both ways? And mention why not to use one over the other? I dunno I am just following my heart. (If @wp starts frowning I will revise and redo the page)

Let me ask you a question ok, if I may. Forget that you are comfortable and highly experienced with fpc and Lazarus. Forget that by looking at someone's code you can instantly spot where he/she has gone wrong. (That comes with many years of grunt work and hacking code.) Remember when you first started with fpc and Lazarus? And if you were looking for documentation would you rather have to skip jump and hop all over the internet searching? Or would you prefer something short and simple in one place but accurate and with some code you can actually run and test and learn? ( on second thoughts you do not have to answer that )

Sources for those docs are in the Lazarus distribution (also available as help files with F1). And corrections can be submitted as merge-request or patch against the git repository.  Files can be edited using fpdoc. (several utilities available, including one build into the IDE)

You can still add content to the wiki, like usage examples and what it will look like.

I will as and when time permits me to do so :-)

[wp]

I wanted to keep it simple. This is why I stuck with just the form.

That's fine, you can demonstrate the Rectangle method by drawing on a form Canvas. I just mentioned Paintbox and Panel because they have an OnPaint method, too.

[Martin_fr]

I didn't mean to "oppose" your content, apologies if it came across that way. But I couldn't tell if you know the docs or not. And consequently I did not know, if you were about to rewrite what is already there, or to add a different angle to it. (I now know it is the latter).

[Aruna]

I didn't mean to "oppose" your content, apologies if it came across that way. But I couldn't tell if you know the docs or not. And consequently I did not know, if you were about to rewrite what is already there, or to add a different angle to it. (I now know it is the latter).

Why are you apologizing? I am quite used to this. This comes with the turf we have chosen to be part of. Peer review can be most times encouraging and motivating and sometimes so scathing you want to disappear straight down into a hole in the ground out of sheer embarrassment. All I am saying is if your coming from an old school like me way way back in the late 80's  or early 90's and your best friend(s) were Clipper 5.3 and Blinker and friends you would probably be an expert in procedural and functional programming, and not so much an object-oriented programmer? Which is the case with me. So when I first saw this:

Code: Pascal  [Select][+][-]

1. public procedure TCanvas.Rectangle(
2.   X1: Integer;
3.   Y1: Integer;
4.   X2: Integer;
5.   Y2: Integer
6. ); virtual;
7.  
8. procedure TCanvas.Rectangle(
9.   const ARect: TRect
10. );

The only things I understood was oh-kay this is a procedure that draws a rectangle and those are the top,left,right and bottom coordinates. I had no clue why it said public procedure or why it said virtual and I totally did not understand how can we have two procedures with the exact same name? how is that even possible? When I saw const Arect: Trect I got up and went for a walk ( yes I felt really dumb and foolish)

I started reading and Googling and now I have a somewhat fair idea on what those mean but still it would be nice for a newcomer to have a page where these thinsg are explained with short code examples? Then we drop the learning curve to near zero imho. So please do not apologize as how can you possibly know the intent unless I explain it first? :-)

[dsiders]

All I am saying is if your coming from an old school like me way way back in the late 80's  or early 90's and your best friend(s) were Clipper 5.3 and Blinker and friends you would probably be an expert in procedural and functional programming, and not so much an object-oriented programmer?

Been there, done that. I still miss Eval blocks. And Classy was a real eye opener for me.

I would suggest that any introductory Object Pascal book should give you a better grasp of OOP and how it's implemented in Lazarus (and Delphi). Lots of good suggestions here:

https://forum.lazarus.freepascal.org/index.php?topic=51036.0
https://wiki.freepascal.org/Pascal_and_Lazarus_Books_and_Magazines?

[Aruna]

Been there, done that. I still miss Eval blocks. And Classy was a real eye opener for me.

You miss Eval blocks? That yearning for the past is easily resolved.

I would suggest that any introductory Object Pascal book should give you a better grasp of OOP and how it's implemented in Lazarus (and Delphi). Lots of good suggestions here:

https://forum.lazarus.freepascal.org/index.php?topic=51036.0
https://wiki.freepascal.org/Pascal_and_Lazarus_Books_and_Magazines?

Many many thanks :-)

[wp]

You can see what I have done here:
Canvas.Rectangle
Maybe I should split things up into separate pages? What does everyone else think? I would like to 'clearly' separate the content from where it says 'Another Example'

Let me comment on your wiki page referred to above.

Most of all: After a week or so you did not change that page any more, and I get the impression that you gave up on this activity and left this half-finished page. I don't want to discourage you, but incomplete articles are a wiki nuisance next to out-dated articels.

I don't like the idea of splitting "Another example" off of the main page, in particular when the split-off page is just named "Examples". This pollutes the wiki directory with general names which are meaningless if read out of context. The name of the page is essentially the filename in the wiki file structure und thus must be unique. I would prefer a much more compact and "wiki-like" presentation with a "Contents" listing at the top of the page. Then the user has all information on a single page, but still can navigate easily. To create the "contents" part, just put the page name into double curly braces; the "Contents" items are extracted from the header lines of the text. A simple page where this is done, for example, is my CalLite article; go to it and click on the "edit" tab to see the "code".

[Aruna]

You can see what I have done here:
Canvas.Rectangle
Maybe I should split things up into separate pages? What does everyone else think? I would like to 'clearly' separate the content from where it says 'Another Example'

Let me comment on your wiki page referred to above.

Most of all: After a week or so you did not change that page any more, and I get the impression that you gave up on this activity and left this half-finished page. I don't want to discourage you, but incomplete articles are a wiki nuisance next to out-dated articels.

Hi @wp If I had the time I would most certainly be working full-time on the wiki. But no offense life happens you know? If your an almost retireee living on a fixed income and have to put food on the table and juggle the wiki am betting 10 to 1 hunger will be given priority number 1. So, what I do just like you is volunteer my time for what I sincerely beleive is a good cause but this I do as and when time permist me to do so. Does not mean I have given up or abandoned what I started :-)

I don't like the idea of splitting "Another example" off of the main page, in particular when the split-off page is just named "Examples".

The examples link you dislike no longer exists. I removed it. (happy now?). The remaining page content to me looks complete and useful to a complete newbie ( I could be wrong )

This pollutes the wiki directory with general names which are meaningless if read out of context. The name of the page is essentially the filename in the wiki file structure und thus must be unique. I would prefer a much more compact and "wiki-like" presentation with a "Contents" listing at the top of the page. Then the user has all information on a single page, but still can navigate easily. To create the "contents" part, just put the page name into double curly braces; the "Contents" items are extracted from the header lines of the text. A simple page where this is done, for example, is my CalLite article; go to it and click on the "edit" tab to see the "code".

@wp thank you very much for sharing this. I will go through and see how you did this ( as and when time permits me to do so, am just saying :-) Oh by the way I would really appreciate it if you would go through this which I posted last night as a reply and see if teh advice I gave is acceptable?

[wp]

If I had the time I would most certainly be working full-time on the wiki. But no offense life happens you know? If your an almost retireee living on a fixed income and have to put food on the table and juggle the wiki am betting 10 to 1 hunger will be given priority number 1. So, what I do just like you is volunteer my time for what I sincerely beleive is a good cause but this I do as and when time permist me to do so. Does not mean I have given up or abandoned what I started :-)

I don't like the idea of splitting "Another example" off of the main page, in particular when the split-off page is just named "Examples".

The examples link you dislike no longer exists. I removed it. (happy now?). The remaining page content to me looks complete and useful to a complete newbie ( I could be wrong )

Yes, now the page looks fine, and it no longer looks as if its author had given up. Thanks.

A few more ideas for the page (just if you wish - the page is finished as it is):

• There is also an overloaded version of the Rectangle method which accepts a single TRect argument rather than individual x1, y1, x2, y2 arguments.
• When looking at the screenshot of the example I asked myself: Why is the rectangle white? And why does it have a black border? Maybe what is missing is a remark that the appearance of the rectangle is determined by the Brush and Pen properties of the Canvas. Why not add another example which draws a red rectangle with blue dashed border, or something else like this?
• Maybe you should also mention other Canvas methods which have the same set of arguments:
  - FillRect(...) which draws a border-less rectangle
  - Frame(...) and FrameRect(...) which draw a border-only rectangle, the first one using the Pen, the second one using the Brush.
  - Ellipse(...) which draws an ellipse into the enclosing rectangle,
  - maybe also RoundRect which draws a rectangle with rounded corners but needs two more parameters for the horizontal and vertical radii at the corners
  - and maybe also GradientFill which fills the rectangle with a color gradient between two specified colors in the specified direction (requires also more arguments).
  - Finally Frame3D(...) which draws a 3D-like rectangle with given colors for the top/left and bottom/right edges. It's a bit different from the other methods since the rectangle must be specified as a var TRect parameter.
• Maybe you should also mention a misconception regarding the right and bottom parameters of the functions: These values are not included in the drawn rectangle. So, when you draw a rectangle from Left = 10 to Right = 10, nothing is drawn. Going from Left=10 to Right = 11, however, the drawing is 1 pixel wide. There was a discussion about this in the forum some months ago.
• You probably should also provide links to the official documentation, e.g. https://lazarus-ccr.sourceforge.io/docs/lcl/graphics/tcanvas.rectangle.html

Code: Pascal  [Select][+][-]

1. procedure TForm1.FormPaint(Sender: TObject);
2. var
3.   R: TRect;
4. begin
5.   // Filled rectangle, no border
6.   Canvas.Brush.Color := clBlue;
7.   Canvas.FillRect(10, 10, 100, 100);
8.  
9.   // Non-filled rectangle
10.   Canvas.Brush.Color := clRed;
11.   Canvas.FrameRect(110, 10, 200, 100);
12.  
13.   // Non-filled rectangle
14.   Canvas.Pen.Color := clGreen;
15.   Canvas.Frame(210, 10, 300, 100);
16.  
17.   // Ellipse (Circle)
18.   Canvas.Pen.Color := clBlue;
19.   Canvas.Pen.Style := psDash;
20.   Canvas.Brush.Color := clRed;
21.   Canvas.Brush.Style := bsCross;
22.   Canvas.Ellipse(10, 110, 100, 200);
23.  
24.   // Ellipse
25.   Canvas.Pen.style := psSolid;
26.   Canvas.Pen.Color := clBlue;
27.   Canvas.Brush.Color := clAqua;
28.   Canvas.Brush.Style := bsSolid;
29.   Canvas.RoundRect(110, 110, 200, 200, 20, 20);
30.  
31.   // Rectangle filled by vertical gradient
32.   Canvas.Pen.Style := psSolid;
33.   Canvas.GradientFill(Rect(210, 110, 300, 200), clRed, clYellow, gdVertical);
34.  
35.   // Raised empty 3D rectangle
36.   Canvas.Pen.Style := psSolid;
37.   R := Rect(10, 210, 100, 300);
38.   Canvas.Frame3D(R, clWhite, clGray, 3);
39.  
40.   // Sunken filled 3D-rectangle
41.   R := Rect(110, 210, 200, 300);
42.   Canvas.Frame3D(R, clGray, clWhite, 3);
43.   Canvas.Brush.Color := clSilver;
44.   Canvas.FillRect(R);
45. end;

Oh by the way I would really appreciate it if you would go through this which I posted last night as a reply and see if teh advice I gave is acceptable?

Yes, I agree, but I also agree with Juha that too much information in the wiki is out-dated and should be removed. So, don't be too hesitant when you are convinced that some sentences or paragraphs are not longer valid. But of course, you can always ask here before deleting/overwriting them.

[Aruna]

A few more ideas for the page (just if you wish - the page is finished as it is):

• There is also an overloaded version of the Rectangle method which accepts a single TRect argument rather than individual x1, y1, x2, y2 arguments.

Done !

• When looking at the screenshot of the example I asked myself: Why is the rectangle white? And why does it have a black border? Maybe what is missing is a remark that the appearance of the rectangle is determined by the Brush and Pen properties of the Canvas. Why not add another example which draws a red rectangle with blue dashed border, or something else like this?

Done ( Please check and review?)

• Maybe you should also mention other Canvas methods which have the same set of arguments:
  - FillRect(...) which draws a border-less rectangle
  - Frame(...) and FrameRect(...) which draw a border-only rectangle, the first one using the Pen, the second one using the Brush.
  - Ellipse(...) which draws an ellipse into the enclosing rectangle,
  - maybe also RoundRect which draws a rectangle with rounded corners but needs two more parameters for the horizontal and vertical radii at the corners
  - and maybe also GradientFill which fills the rectangle with a color gradient between two specified colors in the specified direction (requires also more arguments).
  - Finally Frame3D(...) which draws a 3D-like rectangle with given colors for the top/left and bottom/right edges. It's a bit different from the other methods since the rectangle must be specified as a var TRect parameter.

Working on these slowly as time permits :-)

• Maybe you should also mention a misconception regarding the right and bottom parameters of the functions: These values are not included in the drawn rectangle. So, when you draw a rectangle from Left = 10 to Right = 10, nothing is drawn. Going from Left=10 to Right = 11, however, the drawing is 1 pixel wide. There was a discussion about this in the forum some months ago.

I will do so...

• You probably should also provide links to the official documentation, e.g. https://lazarus-ccr.sourceforge.io/docs/lcl/graphics/tcanvas.rectangle.html

I put the link at the very top since you like things that way but may not be where it is supposed to be, so please double check and let me know if this is ok. Here is the link

[wp]

Please check and review?

Nice.

Added screenshots with all brush and pen styles, I think this way these identifiers are clearer than just listing them.