Fl::awake() docs example

[Greg Ercolano]

Given the recent Q+A on fltkgeneral, "Subject: Fl::awake on linux dont work",

I'd like to add this short code example in the doxygen docs for Fl::awake(func,data) to demonstrate how calling Fl::lock() is required before using it:

    \code
    [..]
    void test_awake_cb(void*) {
        std::cout << "FL::AWAKE Worked!\n" << std::flush;
    }
    int main() {
        Fl_Window win(300,300);
        [..]
        Fl::lock();                         // call early, before using Fl::awake()
        win.show();
        Fl::awake(test_awake_cb, nullptr);  // use Fl::awake() anytime after Fl::lock()'s first call
        return Fl::run();
    }
    \endcode

It made sense to put this below the text in that doxygen comment section that used to read:

     Nevertheless, the early, single call to Fl::lock() used to initialize threading support is necessary.

..but in a recent commit, this text was removed for some reason? I'm wondering if this was on purpose, or an omission/regression. I added this commit comment mentioning this, but not sure if those comments are easily seen by the commit author, so wanted to draw attention to this here for conversation.

Is it the case "calling Fl::lock() early" is no longer required for Fl::awake() to work in 1.5.x, hence the removal of that line? Or was the doxygen comment that underlines this removed for other purposes, perhaps depending more on the "See Also" references.

I'm guessing it's a regression; seems important to restore that "Nevertheless, the early, single call to Fl::lock()" line, as without it I probably wouldn't have been able to answer the OP's question yesterday; as I don't use Fl:awake() myself.

[imm]

On Sun, 22 Jun 2025, 17:44 Greg wrote:

It made sense to put this below the text in that doxygen comment section that used to read:

     Nevertheless, the early, single call to Fl::lock() used to initialize threading support is necessary.

..but in a recent commit, this text was removed for some reason? I'm wondering if this was on purpose, or an omission/regression. I added this commit comment mentioning this, but not sure if those comments are easily seen by the commit author, so wanted to draw attention to this here for conversation.

Is it the case "calling Fl::lock() early" is no longer required for Fl::awake() to work in 1.5.x, hence the removal of that line? Or was the doxygen comment that underlines this removed for other purposes, perhaps depending more on the "See Also" references.

I'm guessing it's a regression; seems important to restore that "Nevertheless, the early, single call to Fl::lock()" line, as without it I probably wouldn't have been able to answer the OP's question yesterday; as I don't use Fl:awake() myself.

AFAIK it's still required, so like Greg I think this is something that looks like a regression in the docs.

I'd also mention here the "Advanced FLTK" section of the docs, which has quite a lot on this topic so maybe useful to the OP, if they've not already read it.

--
Ian
From my Fairphone FP3

[Albrecht Schlosser]

On 6/22/25 19:10 imm wrote:

On Sun, 22 Jun 2025, 17:44 Greg wrote:

It made sense to put this below the text in that doxygen comment section that used to read:

     Nevertheless, the early, single call to Fl::lock() used to initialize threading support is necessary.

..but in a recent commit, this text was removed for some reason? I'm wondering if this was on purpose, or an omission/regression. I added this commit comment mentioning this, but not sure if those comments are easily seen by the commit author, so wanted to draw attention to this here for conversation.

Is it the case "calling Fl::lock() early" is no longer required for Fl::awake() to work in 1.5.x, hence the removal of that line? Or was the doxygen comment that underlines this removed for other purposes, perhaps depending more on the "See Also" references.

I'm guessing it's a regression; seems important to restore that "Nevertheless, the early, single call to Fl::lock()" line, as without it I probably wouldn't have been able to answer the OP's question yesterday; as I don't use Fl:awake() myself.

AFAIK it's still required, so like Greg I think this is something that looks like a regression in the docs.

Yes, it's still required. Matthias changed lots of the Fl::awake related stuff and tried to update the docs as well. This statement was likely removed by accident when he changed/moved the docs elsewhere.

I'd also mention here the "Advanced FLTK" section of the docs, which has quite a lot on this topic so maybe useful to the OP, if they've not already read it.

Yep, this is also very helpful stuff for users.